Circle Webhook Notifications

asyncapi: 2.6.0
info:
  title: Circle Webhook Notifications
  version: '1.0.0'
  description: |-
    AsyncAPI description of Circle's outbound webhook (notification) surfaces.
    Circle delivers event notifications by POSTing a JSON body to a subscriber
    endpoint that is registered via product-specific notification-subscription
    APIs. Each notification carries a `notificationType` discriminator that
    identifies the event class.

    Only event types that Circle documents publicly at the time this file was
    authored are modelled. Surfaces that Circle's developer portal references
    only by name (for example legacy Circle Mint payments, payouts, wires,
    cards, transfers, settlements and chargebacks) are not enumerated below
    because the public docs index (`https://developers.circle.com/llms.txt`)
    does not list their event-type strings.

    Modelled products:
      - Circle Payments Network (CPN) — payment, RFI, transaction and refund
        events delivered to the Originating Financial Institution (OFI).
      - Circle Gateway — permissionless cross-chain deposit and mint events.
      - StableFX — Arc-based stablecoin FX trade and on-chain contract events.
      - Smart Contract Platform — onchain event-log notifications from
        user-configured event monitors.
      - Webhooks test — synthetic event used by the "send test notification"
        operation on each subscription resource.

    Source documentation:
      - CPN webhook events:
        https://developers.circle.com/cpn/references/webhooks/webhook-events
      - CPN webhook setup:
        https://developers.circle.com/cpn/guides/webhooks/setup-webhook-notifications
      - Gateway notification subscription OpenAPI:
        https://developers.circle.com/openapi/gateway.yaml
      - StableFX notification subscription OpenAPI:
        https://developers.circle.com/openapi/stablefx.yaml
      - Smart Contract Platform event monitoring:
        https://developers.circle.com/contracts/scp-event-monitoring.md
      - Developer portal index:
        https://developers.circle.com/llms.txt

    Security and signing:
      Each Circle product that exposes a webhook subscription resource also
      exposes a `GET /v2/.../notifications/publicKey/{id}` (or product-prefixed
      equivalent) operation. Outbound POSTs include two headers:
        - `X-Circle-Signature` — digital signature generated by Circle.
        - `X-Circle-Key-Id`    — UUID used as the `id` path parameter when
                                  fetching the verifying public key.
      Subscribers verify the signature against the published public key to
      confirm the notification originated from Circle. The bearer-auth scheme
      below applies to the inbound subscription-management API; the
      signature-verification scheme applies to outbound POSTs.
  contact:
    name: Circle Developer Support
    url: https://developers.circle.com/
  license:
    name: Circle Terms of Service
    url: https://www.circle.com/legal/terms-of-service

defaultContentType: application/json

servers:
  subscriber:
    url: '{webhookUrl}'
    protocol: https
    description: |-
      Customer-hosted HTTPS endpoint that Circle POSTs notifications to. The
      full URL is configured on the subscription resource (`endpoint` field)
      via the product-specific subscription API. Circle requires the endpoint
      to be publicly reachable, use HTTPS, and respond with a 2XX status to
      a POST request.
    variables:
      webhookUrl:
        default: https://example.org/handler/for/notifications
        description: Fully-qualified HTTPS URL of the subscriber endpoint.
    security:
      - circleSignature: []

channels:
  /circle/cpn:
    description: |-
      Subscriber endpoint that receives Circle Payments Network notifications
      for an OFI. A single subscription delivers payment lifecycle, RFI,
      onchain transaction and refund events. Subscribe with
      `notificationTypes: ["*"]` to receive every CPN event.
    bindings:
      http:
        type: request
        method: POST
        bindingVersion: '0.3.0'
    publish:
      operationId: receiveCpnNotification
      summary: Receive a CPN webhook notification
      description: |-
        Circle POSTs a JSON notification to the subscriber endpoint when a
        CPN payment, RFI, transaction or refund changes state. The
        `notificationType` field on the body identifies the event class.
      message:
        oneOf:
          - $ref: '#/components/messages/CpnPaymentCryptoFundsPending'
          - $ref: '#/components/messages/CpnPaymentFiatPaymentInitiated'
          - $ref: '#/components/messages/CpnPaymentCompleted'
          - $ref: '#/components/messages/CpnPaymentFailed'
          - $ref: '#/components/messages/CpnPaymentDelayed'
          - $ref: '#/components/messages/CpnPaymentInManualReview'
          - $ref: '#/components/messages/CpnRfiInformationRequired'
          - $ref: '#/components/messages/CpnRfiInReview'
          - $ref: '#/components/messages/CpnRfiApproved'
          - $ref: '#/components/messages/CpnRfiRejected'
          - $ref: '#/components/messages/CpnTransactionBroadcasted'
          - $ref: '#/components/messages/CpnTransactionCompleted'
          - $ref: '#/components/messages/CpnTransactionFailed'
          - $ref: '#/components/messages/CpnRefundCreated'
          - $ref: '#/components/messages/CpnRefundFailed'
          - $ref: '#/components/messages/CpnRefundCompleted'

  /circle/gateway:
    description: |-
      Subscriber endpoint that receives Circle Gateway permissionless
      notifications. Subscribers can filter by `notificationTypes`,
      `addresses` and `domains` on the subscription resource. Use
      `gateway.*` to subscribe to all current and future Gateway notification
      types.
    bindings:
      http:
        type: request
        method: POST
        bindingVersion: '0.3.0'
    publish:
      operationId: receiveGatewayNotification
      summary: Receive a Gateway webhook notification
      description: |-
        Circle POSTs a JSON notification when a Gateway deposit or mint
        reaches a finalized state, or when a mint is forwarded between
        domains. The `notificationType` field identifies the event class.
      message:
        oneOf:
          - $ref: '#/components/messages/GatewayDepositFinalized'
          - $ref: '#/components/messages/GatewayMintFinalized'
          - $ref: '#/components/messages/GatewayMintForwarded'

  /circle/stablefx:
    description: |-
      Subscriber endpoint that receives StableFX notifications for Arc-based
      stablecoin FX trades. Subscribers can subscribe to specific trade or
      contract events, or use `stablefx.trade.*` / `stablefx.contract.*`
      wildcards, or `*` to receive every StableFX event.
    bindings:
      http:
        type: request
        method: POST
        bindingVersion: '0.3.0'
    publish:
      operationId: receiveStableFxNotification
      summary: Receive a StableFX webhook notification
      description: |-
        Circle POSTs a JSON notification when a StableFX trade progresses
        through its lifecycle, or when an on-chain settlement contract call
        fails. The `notificationType` field identifies the event class.
      message:
        oneOf:
          - $ref: '#/components/messages/StableFxTradeConfirmed'
          - $ref: '#/components/messages/StableFxTradePendingSettlement'
          - $ref: '#/components/messages/StableFxTradeMakerFunded'
          - $ref: '#/components/messages/StableFxTradeTakerFunded'
          - $ref: '#/components/messages/StableFxTradeCompleted'
          - $ref: '#/components/messages/StableFxTradeRefunded'
          - $ref: '#/components/messages/StableFxTradeFailed'
          - $ref: '#/components/messages/StableFxTradeBreached'
          - $ref: '#/components/messages/StableFxContractRecordTradeFailed'
          - $ref: '#/components/messages/StableFxContractMakerDeliverFailed'
          - $ref: '#/components/messages/StableFxContractTakerDeliverFailed'

  /circle/contracts:
    description: |-
      Subscriber endpoint that receives Smart Contract Platform event-log
      notifications. The webhook fires when an event matching a configured
      event monitor is observed onchain.
    bindings:
      http:
        type: request
        method: POST
        bindingVersion: '0.3.0'
    publish:
      operationId: receiveContractsNotification
      summary: Receive a Smart Contract Platform event-log notification
      description: |-
        Circle POSTs a JSON notification when a smart contract emits an
        event that matches a configured event monitor. The body includes the
        event signature, contract address, blockchain, transaction hash,
        topics, raw data and a timestamp.
      message:
        $ref: '#/components/messages/ContractsEventLog'

  /circle/webhooks-test:
    description: |-
      Synthetic notification used by the "send test notification" operation
      on each Circle subscription resource (for example
      `POST /v2/notifications/subscriptions/permissionless/{id}/test`).
      Delivered to the same subscriber endpoint as production notifications.
    bindings:
      http:
        type: request
        method: POST
        bindingVersion: '0.3.0'
    publish:
      operationId: receiveWebhooksTest
      summary: Receive a Circle test notification
      description: |-
        Test notification dispatched by Circle when an operator triggers the
        subscription "send test notification" endpoint. The body carries the
        `notificationType` value `webhooks.test`.
      message:
        $ref: '#/components/messages/WebhooksTest'

components:
  securitySchemes:
    circleSignature:
      type: httpApiKey
      description: |-
        Circle signs every outbound webhook POST. Subscribers verify the
        `X-Circle-Signature` header using the public key returned by
        `GET /v2/.../notifications/publicKey/{id}` (or the product-specific
        equivalent), where `{id}` is the UUID delivered in the
        `X-Circle-Key-Id` header on the same request.
      name: X-Circle-Signature
      in: header

  messages:
    # --- CPN Payment Events ---
    CpnPaymentCryptoFundsPending:
      name: CpnPaymentCryptoFundsPending
      title: cpn.payment.cryptoFundsPending
      summary: The payment has been created and is waiting for funds to be deposited.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnPaymentEnvelope'
    CpnPaymentFiatPaymentInitiated:
      name: CpnPaymentFiatPaymentInitiated
      title: cpn.payment.fiatPaymentInitiated
      summary: The BFI has initiated the fiat payment to the receiver's bank account.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnPaymentEnvelope'
    CpnPaymentCompleted:
      name: CpnPaymentCompleted
      title: cpn.payment.completed
      summary: The payment is fully processed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnPaymentEnvelope'
    CpnPaymentFailed:
      name: CpnPaymentFailed
      title: cpn.payment.failed
      summary: |-
        The payment failed due to errors in processing, insufficient funds,
        or compliance rejection.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnPaymentEnvelope'
    CpnPaymentDelayed:
      name: CpnPaymentDelayed
      title: cpn.payment.delayed
      summary: There is a delay to the estimate of payment settlement time.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnPaymentEnvelope'
    CpnPaymentInManualReview:
      name: CpnPaymentInManualReview
      title: cpn.payment.inManualReview
      summary: A manual review has been placed on the payment.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnPaymentEnvelope'

    # --- CPN RFI Events ---
    CpnRfiInformationRequired:
      name: CpnRfiInformationRequired
      title: cpn.rfi.informationRequired
      summary: |-
        Additional compliance information is needed before the payment can
        proceed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnRfiEnvelope'
    CpnRfiInReview:
      name: CpnRfiInReview
      title: cpn.rfi.inReview
      summary: The submitted RFI response is under review by the BFI.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnRfiEnvelope'
    CpnRfiApproved:
      name: CpnRfiApproved
      title: cpn.rfi.approved
      summary: The RFI has been reviewed and approved; the payment can proceed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnRfiEnvelope'
    CpnRfiRejected:
      name: CpnRfiRejected
      title: cpn.rfi.rejected
      summary: The RFI has been reviewed and rejected; the payment is failed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnRfiEnvelope'

    # --- CPN Transaction Events ---
    CpnTransactionBroadcasted:
      name: CpnTransactionBroadcasted
      title: cpn.transaction.broadcasted
      summary: The signed transaction is sent to the blockchain for confirmation.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnTransactionEnvelope'
    CpnTransactionCompleted:
      name: CpnTransactionCompleted
      title: cpn.transaction.completed
      summary: The transaction was successfully included in a block.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnTransactionEnvelope'
    CpnTransactionFailed:
      name: CpnTransactionFailed
      title: cpn.transaction.failed
      summary: |-
        The transaction failed due to issues such as incorrect parameters or
        insufficient gas fees.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnTransactionEnvelope'

    # --- CPN Refund Events ---
    CpnRefundCreated:
      name: CpnRefundCreated
      title: cpn.refund.created
      summary: The BFI created a refund for the associated payment.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnRefundEnvelope'
    CpnRefundFailed:
      name: CpnRefundFailed
      title: cpn.refund.failed
      summary: The refund could not be processed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnRefundEnvelope'
    CpnRefundCompleted:
      name: CpnRefundCompleted
      title: cpn.refund.completed
      summary: The refund is complete.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CpnRefundEnvelope'

    # --- Gateway Events ---
    GatewayDepositFinalized:
      name: GatewayDepositFinalized
      title: gateway.deposit.finalized
      summary: A Gateway deposit has been finalized on the source chain.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/GatewayEnvelope'
    GatewayMintFinalized:
      name: GatewayMintFinalized
      title: gateway.mint.finalized
      summary: A Gateway mint has been finalized on the destination chain.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/GatewayEnvelope'
    GatewayMintForwarded:
      name: GatewayMintForwarded
      title: gateway.mint.forwarded
      summary: A Gateway mint has been forwarded between domains.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/GatewayEnvelope'

    # --- StableFX Trade Events ---
    StableFxTradeConfirmed:
      name: StableFxTradeConfirmed
      title: stablefx.trade.confirmed
      summary: A StableFX trade has been confirmed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'
    StableFxTradePendingSettlement:
      name: StableFxTradePendingSettlement
      title: stablefx.trade.pendingSettlement
      summary: A StableFX trade is pending settlement.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'
    StableFxTradeMakerFunded:
      name: StableFxTradeMakerFunded
      title: stablefx.trade.makerFunded
      summary: The maker side of a StableFX trade has been funded.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'
    StableFxTradeTakerFunded:
      name: StableFxTradeTakerFunded
      title: stablefx.trade.takerFunded
      summary: The taker side of a StableFX trade has been funded.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'
    StableFxTradeCompleted:
      name: StableFxTradeCompleted
      title: stablefx.trade.completed
      summary: A StableFX trade has completed settlement.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'
    StableFxTradeRefunded:
      name: StableFxTradeRefunded
      title: stablefx.trade.refunded
      summary: A StableFX trade has been refunded.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'
    StableFxTradeFailed:
      name: StableFxTradeFailed
      title: stablefx.trade.failed
      summary: A StableFX trade failed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'
    StableFxTradeBreached:
      name: StableFxTradeBreached
      title: stablefx.trade.breached
      summary: A StableFX trade was breached.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxTradeEnvelope'

    # --- StableFX Contract Events ---
    StableFxContractRecordTradeFailed:
      name: StableFxContractRecordTradeFailed
      title: stablefx.contract.recordTrade.failed
      summary: The on-chain `recordTrade` settlement contract call failed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxContractEnvelope'
    StableFxContractMakerDeliverFailed:
      name: StableFxContractMakerDeliverFailed
      title: stablefx.contract.makerDeliver.failed
      summary: The on-chain `makerDeliver` settlement contract call failed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxContractEnvelope'
    StableFxContractTakerDeliverFailed:
      name: StableFxContractTakerDeliverFailed
      title: stablefx.contract.takerDeliver.failed
      summary: The on-chain `takerDeliver` settlement contract call failed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StableFxContractEnvelope'

    # --- Smart Contract Platform Event ---
    ContractsEventLog:
      name: ContractsEventLog
      title: contracts.eventLog
      summary: An event log from a smart contract.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ContractsEventLogEnvelope'

    # --- Webhooks Test ---
    WebhooksTest:
      name: WebhooksTest
      title: webhooks.test
      summary: |-
        Synthetic test notification fired by the "send test notification"
        operation on a subscription resource.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WebhooksTestEnvelope'

  schemas:
    # Common envelope fields are kept conservative: only fields that Circle
    # actually documents in its notification payloads are listed. Product
    # payload bodies (e.g. payment, trade) are intentionally open objects
    # because Circle's webhook payload schemas are not separately published
    # in the public OpenAPI specs.

    NotificationEnvelopeBase:
      type: object
      required:
        - notificationType
      properties:
        notificationType:
          type: string
          description: Discriminator identifying the event class.
        environment:
          type: string
          description: Environment that produced the notification.
          enum:
            - TEST
            - LIVE
        subscriptionId:
          type: string
          format: uuid
          description: ID of the subscription that delivered this notification.
        timestamp:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp of the notification.

    CpnPaymentEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              enum:
                - cpn.payment.cryptoFundsPending
                - cpn.payment.fiatPaymentInitiated
                - cpn.payment.completed
                - cpn.payment.failed
                - cpn.payment.delayed
                - cpn.payment.inManualReview
            payment:
              type: object
              description: |-
                CPN payment resource snapshot. Refer to the CPN OFI OpenAPI
                (`https://developers.circle.com/openapi/cpn-ofi.yaml`) for
                the payment schema.
              additionalProperties: true

    CpnRfiEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              enum:
                - cpn.rfi.informationRequired
                - cpn.rfi.inReview
                - cpn.rfi.approved
                - cpn.rfi.rejected
            rfi:
              type: object
              description: |-
                CPN Request For Information resource snapshot. Refer to the
                CPN OFI OpenAPI for the RFI schema.
              additionalProperties: true

    CpnTransactionEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              enum:
                - cpn.transaction.broadcasted
                - cpn.transaction.completed
                - cpn.transaction.failed
            transaction:
              type: object
              description: |-
                CPN onchain transaction resource snapshot. Refer to the CPN
                OFI OpenAPI for the transaction schema.
              additionalProperties: true

    CpnRefundEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              enum:
                - cpn.refund.created
                - cpn.refund.failed
                - cpn.refund.completed
            refund:
              type: object
              description: |-
                CPN refund resource snapshot. Refer to the CPN OFI OpenAPI
                for the refund schema.
              additionalProperties: true

    GatewayEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              enum:
                - gateway.deposit.finalized
                - gateway.mint.finalized
                - gateway.mint.forwarded
            address:
              type: string
              description: |-
                EVM or Solana wallet address the subscription matched on.
            domain:
              type: string
              description: |-
                CCTP domain identifier for the blockchain involved (e.g. `0`
                for Ethereum, `6` for Base, `26` for Arc).
            token:
              type: string
              description: Token symbol; Gateway currently supports `USDC`.
              enum:
                - USDC
            data:
              type: object
              description: |-
                Event-specific payload body. Refer to the Gateway OpenAPI
                (`https://developers.circle.com/openapi/gateway.yaml`).
              additionalProperties: true

    StableFxTradeEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              enum:
                - stablefx.trade.confirmed
                - stablefx.trade.pendingSettlement
                - stablefx.trade.makerFunded
                - stablefx.trade.takerFunded
                - stablefx.trade.completed
                - stablefx.trade.refunded
                - stablefx.trade.failed
                - stablefx.trade.breached
            trade:
              type: object
              description: |-
                StableFX trade resource snapshot. Refer to the StableFX
                OpenAPI (`https://developers.circle.com/openapi/stablefx.yaml`).
              additionalProperties: true

    StableFxContractEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              enum:
                - stablefx.contract.recordTrade.failed
                - stablefx.contract.makerDeliver.failed
                - stablefx.contract.takerDeliver.failed
            contractCall:
              type: object
              description: |-
                On-chain settlement contract call detail. Refer to the
                StableFX OpenAPI for the schema.
              additionalProperties: true

    ContractsEventLogEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              const: contracts.eventLog
            eventLog:
              type: object
              description: |-
                Smart contract event log. Documented fields include
                `blockchain`, `contractAddress`, `eventSignature`,
                `eventSignatureHash`, `txHash`, `topics`, `data`,
                `blockHash`, `blockHeight`, `logIndex` and
                `firstConfirmDate`. Refer to the Smart Contract Platform
                OpenAPI
                (`https://developers.circle.com/openapi/smart-contract-platform.yaml`).
              additionalProperties: true

    WebhooksTestEnvelope:
      allOf:
        - $ref: '#/components/schemas/NotificationEnvelopeBase'
        - type: object
          properties:
            notificationType:
              type: string
              const: webhooks.test