bff for callbacks

interface/api.yaml

@@ -23,6 +23,8 @@ tags:
     description: Recipient CRUD and archive flows
   - name: Payment Methods
     description: Payment method CRUD and archive flows
+  - name: Callbacks
+    description: Webhook callback subscription CRUD and signing secret rotation
   - name: Payments
     description: Quotation and payment orchestration
 
@@ -70,6 +72,19 @@ paths:
   /payment_methods/archive/{organizations_ref}/{payment_methods_ref}:
     $ref: ./api/payment_methods/archive.yaml
 
+  /callbacks/list/{org_ref}/{organizations_ref}:
+    $ref: ./api/callbacks/list.yaml
+  /callbacks/{org_ref}:
+    $ref: ./api/callbacks/create.yaml
+  /callbacks/{callbacks_ref}:
+    $ref: ./api/callbacks/object.yaml
+  /callbacks:
+    $ref: ./api/callbacks/update.yaml
+  /callbacks/archive/{org_ref}/{callbacks_ref}:
+    $ref: ./api/callbacks/archive.yaml
+  /callbacks/rotate-secret/{callbacks_ref}:
+    $ref: ./api/callbacks/rotate_secret.yaml
+
   /payments/quote/{organizations_ref}:
     $ref: ./api/payments/quote.yaml
   /payments/multiquote/{organizations_ref}:

interface/api/callbacks/archive.yaml

@@ -0,0 +1,38 @@
+get:
+  tags: [Callbacks]
+  summary: Archive/unarchive callback subscription
+  description: Sets callback archive state by `callbacks_ref` and required `archived` query parameter.
+  operationId: callbacksArchive
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+    - name: archived
+      in: query
+      required: true
+      description: Target archive value to set on the callback.
+      schema:
+        type: boolean
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Archive state updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/bodies/callback.yaml

@@ -0,0 +1,9 @@
+components:
+  requestBodies:
+    CallbackBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/callback.yaml#/components/schemas/CallbackRequest
+

interface/api/callbacks/create.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Callbacks]
+  summary: Create callback subscription
+  description: Creates callback subscription for the organization identified by `org_ref`.
+  operationId: callbacksCreate
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+  requestBody:
+    $ref: ./bodies/callback.yaml#/components/requestBodies/CallbackBody
+  responses:
+    '201':
+      description: Callback created
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/list.yaml

@@ -0,0 +1,34 @@
+get:
+  tags: [Callbacks]
+  summary: List callback subscriptions
+  description: Lists callbacks for the given organization context.
+  operationId: callbacksList
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - $ref: ../parameters/limit.yaml#/components/parameters/Limit
+    - $ref: ../parameters/offset.yaml#/components/parameters/Offset
+    - $ref: ../parameters/archived.yaml#/components/parameters/Archived
+  responses:
+    '200':
+      description: Callback list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/object.yaml

@@ -0,0 +1,65 @@
+get:
+  tags: [Callbacks]
+  summary: Get callback subscription
+  description: Returns callback subscription by `callbacks_ref`.
+  operationId: callbacksGet
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+  responses:
+    '200':
+      description: Callback data
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+
+delete:
+  tags: [Callbacks]
+  summary: Delete callback subscription
+  description: Deletes callback by reference.
+  operationId: callbacksDelete
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Callback deleted
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/request/callback.yaml

@@ -0,0 +1,5 @@
+components:
+  schemas:
+    CallbackRequest:
+      $ref: ../../../models/callback/callback.yaml#/components/schemas/Callback
+

interface/api/callbacks/response/callback.yaml

@@ -0,0 +1,19 @@
+components:
+  schemas:
+    CallbacksAuthData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - callbacks
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        callbacks:
+          type: array
+          items:
+            $ref: ../../../models/callback/callback.yaml#/components/schemas/Callback
+        generatedSigningSecret:
+          type: string
+          nullable: true
+

interface/api/callbacks/rotate_secret.yaml

@@ -0,0 +1,32 @@
+post:
+  tags: [Callbacks]
+  summary: Rotate callback signing secret
+  description: Generates and stores a new HMAC secret for the callback in Vault and returns it once.
+  operationId: callbacksRotateSecret
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/callbacks_ref.yaml#/components/parameters/CallbacksRef
+  responses:
+    '200':
+      description: Callback secret rotated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/callbacks/update.yaml

@@ -0,0 +1,32 @@
+put:
+  tags: [Callbacks]
+  summary: Update callback subscription
+  description: Updates callback subscription fields.
+  operationId: callbacksUpdate
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/callback.yaml#/components/requestBodies/CallbackBody
+  responses:
+    '200':
+      description: Callback updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/callback.yaml#/components/schemas/CallbacksAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+

interface/api/parameters/callbacks_ref.yaml

@@ -0,0 +1,10 @@
+components:
+  parameters:
+    CallbacksRef:
+      name: callbacks_ref
+      in: path
+      required: true
+      description: Callback subscription reference (Mongo ObjectId, 24 hex chars).
+      schema:
+        $ref: ../../models/objectid.yaml#/components/schemas/ObjectId
+

interface/models/callback/callback.yaml

@@ -0,0 +1,67 @@
+components:
+  schemas:
+    CallbackRetryPolicy:
+      type: object
+      additionalProperties: false
+      required:
+        - minDelayMs
+        - maxDelayMs
+        - signingMode
+        - maxAttempts
+        - requestTimeoutMs
+      properties:
+        minDelayMs:
+          type: integer
+          minimum: 1
+        maxDelayMs:
+          type: integer
+          minimum: 1
+        signingMode:
+          type: string
+          enum:
+            - none
+            - hmac_sha256
+        secretRef:
+          type: string
+          nullable: true
+        headers:
+          type: object
+          additionalProperties:
+            type: string
+        maxAttempts:
+          type: integer
+          minimum: 1
+        requestTimeoutMs:
+          type: integer
+          minimum: 1
+
+    Callback:
+      allOf:
+        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          additionalProperties: false
+          required:
+            - clientId
+            - status
+            - url
+            - eventTypes
+            - retryPolicy
+          properties:
+            clientId:
+              type: string
+            status:
+              type: string
+              enum:
+                - active
+                - disabled
+            url:
+              type: string
+              format: uri
+            eventTypes:
+              type: array
+              items:
+                type: string
+            retryPolicy:
+              $ref: '#/components/schemas/CallbackRetryPolicy'
+