Quant Network Flow Webhooks API

openapi: 3.2.0
info:
  title: Overledger Server Flow Webhooks API
  description: The Overledger Server is the primary client-facing gateway.
  version: 1.0.0
servers:
- url: https://fusion-rollup.quant.dev
  description: Testnet (live) — the public Fusion Server endpoint
- url: http://localhost:8080
  description: Local development
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Flow Webhooks
  description: Outbound webhook subscriptions and event replay
paths:
  /flow/apps/{appId}/events:
    get:
      tags:
      - Flow Webhooks
      operationId: replayEvents
      summary: List / replay webhook events for a Flow App
      description: 'Returns persisted webhook events for the app. Supports cursor-based pagination

        with `after` (eventId) and optional `eventType` filtering.'
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      - name: eventType
        in: query
        schema:
          type: string
        description: Filter by event type
      - name: after
        in: query
        schema:
          type: string
        description: Cursor — return events after this eventId
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Paginated events
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - hasMore
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEvent'
                  hasMore:
                    type: boolean
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '404':
          $ref: '#/components/responses/FlowNotFound'
  /flow/apps/{appId}/subscriptions:
    post:
      tags:
      - Flow Webhooks
      operationId: createSubscription
      summary: Subscribe to webhook events for a Flow App
      description: 'Creates a webhook subscription. Events matching `eventType` will be delivered

        to `targetUrl` with HMAC-SHA256 signature validation using the provided `secret`.

        The `targetUrl` must not resolve to a private/loopback IP (SSRF protection).'
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - eventType
              - targetUrl
              - secret
              properties:
                eventType:
                  type: string
                  minLength: 1
                  maxLength: 100
                  pattern: ^[a-zA-Z0-9._-]+$
                  description: Event type to subscribe to (e.g. "contact.requested", "step_submitted")
                targetUrl:
                  type: string
                  format: uri
                  description: HTTPS URL to receive webhook deliveries (no private IPs)
                secret:
                  type: string
                  minLength: 16
                  description: Shared secret for HMAC-SHA256 signature verification
      responses:
        '201':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '400':
          $ref: '#/components/responses/FlowBadRequest'
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '404':
          $ref: '#/components/responses/FlowNotFound'
    get:
      tags:
      - Flow Webhooks
      operationId: listSubscriptions
      summary: List webhook subscriptions for a Flow App
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Subscriptions list
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '404':
          $ref: '#/components/responses/FlowNotFound'
  /flow/apps/{appId}/subscriptions/{subscriptionId}:
    delete:
      tags:
      - Flow Webhooks
      operationId: deleteSubscription
      summary: Delete a webhook subscription
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Subscription deleted
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '404':
          $ref: '#/components/responses/FlowNotFound'
components:
  schemas:
    ProblemDetails:
      type: object
      description: RFC 7807 Problem Details — used by all /flow/* endpoints
      required:
      - type
      - title
      - status
      - detail
      - retryable
      properties:
        type:
          type: string
          description: Error classification URI
          example: urn:fusion:error:bad-request
        title:
          type: string
          example: Bad Request
        status:
          type: integer
          example: 400
        detail:
          type: string
          example: appId is required
        retryable:
          type: boolean
          description: Whether the client should retry this request
        instance:
          type: string
          description: Request ID for correlation
    WebhookSubscription:
      type: object
      required:
      - subscriptionId
      - appId
      - eventType
      - targetUrl
      - createdAt
      properties:
        subscriptionId:
          type: string
        appId:
          type: string
        eventType:
          type: string
        targetUrl:
          type: string
          format: uri
        createdAt:
          type: string
          format: date-time
    WebhookEvent:
      type: object
      required:
      - eventId
      - eventType
      - sessionId
      - payload
      - status
      - createdAt
      properties:
        eventId:
          type: string
        eventType:
          type: string
        sessionId:
          type: string
        payload:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
          - pending
          - delivered
          - failed
        createdAt:
          type: string
          format: date-time
  responses:
    FlowUnauthorized:
      description: Unauthorized (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:unauthorized
            title: Unauthorized
            status: 401
            detail: Invalid client credentials
            retryable: false
    FlowNotFound:
      description: Not found (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:not-found
            title: Not Found
            status: 404
            detail: Session not found
            retryable: false
    FlowBadRequest:
      description: Bad request (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:bad-request
            title: Bad Request
            status: 400
            detail: appId is required
            retryable: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'A Keycloak access token (JWT), verified against the realm JWKS

        (signature / issuer / expiry). The caller''s identity is the token''s

        `sub` claim — this is **not** a `clientId`.

        '
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'An Overledger-issued API key of the form `fk_<keyId>.<secret>`, minted via

        `POST /users/me/api-keys`. Accepted on any route and **takes precedence**

        over the `Authorization` header when both are supplied. Resolves to the

        same identity (Keycloak `sub`) as the equivalent Bearer JWT.

        '
x-provenance:
  method: searched
  source: https://docs.overledger.dev/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.overledger.dev/reference/checkdepositstatus.md
  - https://docs.overledger.dev/reference/checkswapstatus.md
  - https://docs.overledger.dev/reference/checkwithdrawalstatus.md
  - https://docs.overledger.dev/reference/createdeposit.md
  - https://docs.overledger.dev/reference/createsession.md
  - https://docs.overledger.dev/reference/createsubscription.md
  - https://docs.overledger.dev/reference/createswap.md
  - https://docs.overledger.dev/reference/createwithdrawal.md
  - https://docs.overledger.dev/reference/delete_deployed-contracts-contractaddress-permissions.md
  - https://docs.overledger.dev/reference/delete_nodes-nodeid.md
  - https://docs.overledger.dev/reference/deletesubscription.md
  - https://docs.overledger.dev/reference/get_deployed-contracts-contractaddress-permissions.md
  - https://docs.overledger.dev/reference/get_deployed-contracts-contractaddress.md
  - https://docs.overledger.dev/reference/get_health.md
  - https://docs.overledger.dev/reference/get_metrics.md
  - https://docs.overledger.dev/reference/get_networks-fusion.md
  - https://docs.overledger.dev/reference/get_networks-total.md
  - https://docs.overledger.dev/reference/get_networks.md
  - https://docs.overledger.dev/reference/get_ready.md
  - https://docs.overledger.dev/reference/get_stakes-address.md
  - https://docs.overledger.dev/reference/get_users-me-access-details.md
  - https://docs.overledger.dev/reference/get_users-me-deployed-contracts.md
  - https://docs.overledger.dev/reference/get_users-me-id.md
  - https://docs.overledger.dev/reference/get_users-me-nodes.md
  - https://docs.overledger.dev/reference/get_users-me-providers.md
  - https://docs.overledger.dev/reference/get_users-me-stakes-total.md
  - https://docs.overledger.dev/reference/get_users-me-stakes.md
  - https://docs.overledger.dev/reference/get_users-me-transactions.md
  - https://docs.overledger.dev/reference/getactionablewithdrawals.md
  - https://docs.overledger.dev/reference/getallowedcomponents.md
  - https://docs.overledger.dev/reference/getapp.md
  - https://docs.overledger.dev/reference/getdeposit.md
  - https://docs.overledger.dev/reference/getdepositallowance.md
  - https://docs.overledger.dev/reference/getdepositbalances.md
  - https://docs.overledger.dev/reference/getsession.md
  - https://docs.overledger.dev/reference/getstep.md
  - https://docs.overledger.dev/reference/getsupportedswaptokens.md
  - https://docs.overledger.dev/reference/getswap.md
  - https://docs.overledger.dev/reference/getswapquote.md
  - https://docs.overledger.dev/reference/gettransactionstatus.md
  - https://docs.overledger.dev/reference/getuserhistory.md
  - https://docs.overledger.dev/reference/getuserswaps.md
  - https://docs.overledger.dev/reference/getuserwithdrawals.md
  - https://docs.overledger.dev/reference/getwithdrawalbyid.md
  - https://docs.overledger.dev/reference/listaddressevents.md
  - https://docs.overledger.dev/reference/listapikeys.md
  - https://docs.overledger.dev/reference/listapps.md
  - https://docs.overledger.dev/reference/listeventsubscriptionevents.md
  - https://docs.overledger.dev/reference/listsessions.md
  - https://docs.overledger.dev/reference/listsubscriptions.md
  - https://docs.overledger.dev/reference/listuserdeposits.md
  - https://docs.overledger.dev/reference/mintapikey.md
  - https://docs.overledger.dev/reference/post_deployed-contracts-contractaddress-permissions.md
  - https://docs.overledger.dev/reference/post_nodes.md
  - https://docs.overledger.dev/reference/post_rpc-apikey.md
  - https://docs.overledger.dev/reference/post_stakes.md
  - https://docs.overledger.dev/reference/post_users-me-providers-providerid-reactivate.md
  - https://docs.overledger.dev/reference/put_deployed-contracts-contractaddress.md
  - https://docs.overledger.dev/reference/put_users-me-providers-providerid-reset-policy.md
  - https://docs.overledger.dev/reference/queryappstate.md
  - https://docs.overledger.dev/reference/recordfinalizetx.md
  - https://docs.overledger.dev/reference/recordprovetx.md
  - https://docs.overledger.dev/reference/replayevents.md
  - https://docs.overledger.dev/reference/revokeapikey.md
  - https://docs.overledger.dev/reference/submitstep.md
  - https://docs.overledger.dev/reference/subscribeaddress.md
  - https://docs.overledger.dev/reference/subscribeevent.md
  - https://docs.overledger.dev/reference/tracktransaction.md
  - https://docs.overledger.dev/reference/unsubscribeaddress.md
  - https://docs.overledger.dev/reference/unsubscribeevent.md
  merge:
    pages: 70
    deduped: 480
    conflicts_kept_first: 0