Webhook events

Reference for CPN webhooks for OFIs: payment, RFI, transaction, and refund notification types and payloads.

Components of CPN send webhook notifications when events occur, typically for a change in state. These webhook notifications are sent to the OFI so that they can track and manage payments in CPN. The webhooks described in this topic are specific to OFIs only.

All webhook notifications follow the same payload structure. The notificationType field indicates the event type, and the notification field contains the event-specific data object. The notification object schema matches the data field returned by the corresponding API endpoint (see the API reference for details).

JSON

{
  "subscriptionId": "cd198ca6-9fc4-41d6-b6b1-8e2a9c975352",
  "notificationId": "0761b030-0c75-472a-b471-74d90a7e796c",
  // Event type, determines the structure of the notification object
  "notificationType": "cpn.payment.cryptoFundsPending",
  // Event-specific data object, structure varies by notificationType
  // See corresponding section below for the object schema (Payment, RFI, Transaction, or Refund)
  "notification": {
    // Object matching the event type
  },
  "timestamp": "2024-09-30T17:48:05.420577158Z",
  "version": 2
}

The following sections describe the webhook events by component.

Payment events

The notification object has the same schema as the data field returned by Get Payment.

Event name	Description	Trigger when
cpn.payment.cryptoFundsPending	The payment has been created and is waiting for funds to be deposited	The payment is ready to accept crypto funds
cpn.payment.fiatPaymentInitiated	The BFI has initiated the fiat payment to the receiver’s bank account	The onchain transaction is confirmed by the BFI and the BFI initiated the fiat payment
cpn.payment.completed	The payment is fully processed	The fiat payment has been sent. Depending on the payment method, the receiver may or may not have received the transfer. At this point, the CPN payment is complete.
cpn.payment.failed	The payment failed due to errors in processing, insufficient funds, or compliance rejection	The payment can’t proceed due to an issue
cpn.payment.delayed	There is a delay to the estimate of payment settlement time. No status has changed but an updated settlement time is included in the payload	The BFI has an internal issue such that fiat settlement takes longer to process than originally stated
cpn.payment.inManualReview	A manual review has been placed on the payment. The payment status itself remains CREATED.	A payment is created but placed under manual review

RFI events

The notification object has the same schema as the data field returned by Get RFI.

Event name	Description	Trigger when
cpn.rfi.informationRequired	Additional compliance information is needed before the payment can proceed	The BFI requests more information to proceed with the payment
cpn.rfi.inReview	The submitted RFI response is under review by the BFI	The OFI submits the required information through the API endpoint
cpn.rfi.approved	The RFI has been reviewed and approved, the payment can proceed	The BFI approves the submitted information
cpn.rfi.rejected	The RFI has been reviewed and rejected, the payment is failed	The BFI rejects the submitted information

Transaction events

The notification object has the same schema as the data field returned by Get Transaction.

Event name	Description	Trigger when
cpn.transaction.broadcasted	The signed transaction is sent to the blockchain for confirmation	The signed transaction has been broadcast
cpn.transaction.completed	The transaction was successfully included in a block	The blockchain confirms the transaction
cpn.transaction.failed	The transaction failed due to issues such as incorrect parameters or insufficient gas fees	The blockchain failed to confirm the transaction

Refund events

The notification object has the same schema as the data field returned by Get Refund.

Event name	Description	Trigger when
cpn.refund.created	The BFI created a refund for the associated payment	The BFI initiated the refund. Note: Not all BFIs send this event.
cpn.refund.failed	The refund could not be processed	The BFI encountered an error processing the refund
cpn.refund.completed	The refund is complete	The BFI confirms that the refund was successfully returned to the refund address

Webhooks from other Circle products

The event types in the previous sections are delivered through CPN subscriptions. When you also use Programmable Wallets or Circle APIs for liquidity and treasury, you may configure additional webhook subscriptions for those products. Payload shape and notificationType values differ from CPN webhooks.

Product area	Subscription endpoint	Reference
CPN payments	Create subscription (POST /v2/cpn/notifications/subscriptions)	This page and Set up a webhook endpoint
Programmable Wallets	Create subscription (POST /v2/notifications/subscriptions)	Inbound transaction and outbound transaction webhook events
Circle APIs (liquidity)	Create subscription (POST /v1/notifications/subscriptions)	Notifications data models

CPN and other Circle products each enforce their own API keys and notification contracts. Plan separate subscriber endpoints or routing logic if you need all event types in one service.