Webhooks

Breeze uses webhooks to notify your server about important payment events — such as when a payment succeeds, fails, or expires. Webhooks allow your backend to update order statuses and trigger post-payment logic automatically.

🔔 Event Format

Each webhook is sent as a POST request to your configured webhook URL, with a JSON payload in the following format:

{
  "type": "<event-type>",
  "data": {
		...  // event details
  },
  "signature": "<webhook-payload-signature>"
}

type: The type of event (PAYMENT_SUCCEEDED, PAYMENT_EXPIRED, etc.)
data: The full payload with transaction details
signature: A hash used for validating the webhook authenticity

Payment Status Events

{
  "type": "PAYMENT_CREATED",
  "data": {
    "pageId": "pay_abc123xyz",
    "status": "UNPAID",
    "clientReferenceId": "<your-unique-id>",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "currency": "USD",
    "amount": 100,
    "source": "direct"
    // ...
  },
  "signature": "afZiTJ..."
}

{
  "type": "PAYMENT_SUCCEEDED",
  "data": {
    "pageId": "pay_abc123xyz",
    "billingEmail": "[email protected]",
    "status": "PAID",
    "clientReferenceId": "<your-unique-id>",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "currency": "USD",
    "amount": 100,
    "payinDetails": {
      "amount": 100,
      "taxAmount": 6, // this indicates the user has been taxed $0.06
      "currency": "USD",
      "type": "CARD",
      "scheme": "AMEX",
      "last4": "0602",
      "cardType": "CREDIT",
      "bin": "377910",
      "issuer": "DBS BANK LTD",
      "threeDS": {
        "requested": true,
        "authentication_status_code": "Y",
        "flow": "CHALLENGE",
        "eci": "05"
      },
    },
    "source": "direct"
  },
  "signature": "afZiTJ..."
}

{
  "type": "PAYMENT_EXPIRED",
  "data": {
    "pageId": "pay_abc123xyz",
    "status": "EXPIRED",
    "clientReferenceId": "<your-unique-id>",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "currency": "USD",
    "amount": 100,
    "source": "direct"
    // ...
  },
  "signature": "afZiTJ..."
}

Payment KYC & Fraud Reporting Events

{
  "type": "KYC_DATA_REQUIRED",
  "data": {
    "email": "[email protected]"
  },
  "signature": "afZiTJ..."
}

{
  "type": "FRAUD_REPORTED",
  "data": {
    "pageId": "page_abc123xyz",
    "clientReferenceId": "<your-payment-page-unique-id>",
    "fraudReportId": "pay_abc123xyz",
    "fraudReason": "Card Not Present Fraud"
  },
  "signature": "afZiTJ..."
}

Other Payment Events

{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_abc123xyz",
    "customerId": "cus_abc123xyz",
    "dueAt": 1758706742140,
    "expiredAt": 1763890742140,
    "livemode": false,
    "merchantId": "mch_abc123xyz",
    "statusUpdatedAt": 1758704448814,
    "status": "PENDING",
    "amount": 301,
    "currency": "USD",
    "previousInvoiceId": "invc_abc123xyz",
    "subscriptionId": "subs_abc123xyz",
    "paymentPageId": "page_abc123xyz",
    "billingPeriod": {
      "start": 1758706742140,
      "end": 1758710342140
    }
  },
  "signature": "afZiTJ..."
}

{
  "type": "REFUND_STATUS_UPDATE",
  "data": {
    "pageId": "page_abc123xyz",
    "refundId": "ref_pay_abc123xyz",
    "status": "new",
    "refundAmount": 641,
    "pageAmount": 641,
    "currency": "USD",
    "checkoutPaymentId": "pay_abc123xyz",
    "reason": "The refund reason",
    "operator": "[email protected]"
  },
  "signature": "uQ3..."
}

{
  "type": "SUBSCRIPTION_STATUS_UPDATED",
  "data": {
    "id": "subs_abc123xyz",
    "createdAt": 1763717623452,
    "updatedAt": 1768901949735,
    "clientReferenceId": "<your-unique-id>",
    "status": "SUSPENDED",
    "priceId": "prc_abc123xyz",
    "productId": "prd_abc123xyz",
    "amount": 599,
    "currency": "USD",
    "billingCycleConfig": {
      "interval": "week",
      "frequency": 1
    },
    "customerId": "cus_abc123xyz"
  },
  "signature": "4SsvB..."
}

{
  "type": "DISPUTE_STATUS_UPDATE",
  "signature": "example_webhook_signature",
  "dispute": "dp_xxxxxx",
  "data": {
    "id": "dp_xxxxxx", 
    "createdAt": 1757374102012,
    "updatedAt": 1757374102112,
    "sourceUpdatedAt": 1757374132012,
    "livemode": true,
    "email": "[email protected]",
    "paymentPageId": "page_xxxxxx"
  }
}

Payout Status Events

{
  "type": "PAYOUT_PAGE_STATUS_UPDATE",
  "data": {
    "id": "payout_page_abc123xyz",
    "status": "CREATED",
    "amount": 100,
    "fundingCurrency": "USDC",
    "clientReferenceId": "<your-unique-id>",
    "releaseMethod": "AUTOMATIC",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "successReturnUrl": "https://example.com/success",
    "failureReturnUrl": "https://example.com/failure"
		...
  },
  "signature": "DpUx..."
}

{
  "type": "PAYOUT_PAGE_PENDING_STATUS_UPDATE",
  "data": {
    "id": "payout_page_abc123xyz",
    "status": "PENDING",
    "amount": 100,
    "fundingCurrency": "USDC",
    "clientReferenceId": "<your-unique-id>",
    "releaseMethod": "MANUAL",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "successReturnUrl": "https://example.com/success",
    "failureReturnUrl": "https://example.com/failure",
    "pendingStatus": "PENDING_MERCHANT_RELEASE",
		"payoutMethod": "BANK_ACCOUNT",
		...
  },
  "signature": "DpUx..."
}

KYC & Fraud Reporting Events

{
  "type": "KYC_DATA_REQUIRED",
  "data": {
    "email": "[email protected]",
  },
  "signature": "afZiTJ..."
}

{
  "type": "FRAUD_REPORTED",
  "data": {
    "pageId": "page_abc123xyz",
    "clientReferenceId": "<your-payment-page-unique-id>",
    "fraudReportId": "pay_abc123xyz",
    "fraudReason": "Card Not Present Fraud",
  },
  "signature": "afZiTJ..."
}

Membership Change Events

{
  "type": "CONNECT_SUCCEEDED",
  "data": {
    "connectId":"conn_52c1c788d831dcd4",	
    "email":"[email protected]",
    "relationship":"VIEWER"
  },
	"signature": "gbWV..."
}

{
  "type": "CONNECT_DELETED",
  "data": {
    "connectId":"conn_52c1c788d831dcd4",	
    "email":"[email protected]",
    "relationship":"VIEWER"
  },
  "signature": "afZiTJ..."
}

✅ Supported Events

Event Type	Description
PAYMENT_CREATED*	Payment was created, but not yet completed
PAYMENT_SUCCEEDED	Payment was successfully completed
PAYMENT_EXPIRED	Payment was not completed in time
KYC_DATA_REQUIRED	KYC data required from merchant
FRAUD_REPORTED	Payment reported to be fraudulent by card issuer / networks
INVOICE_STATUS_UPDATED	Invoice status updated, possible statuses: `PENDING`, `PAID`, `EXPIRED`, `GRACE_PERIOD`, `CANCELED`.
REFUND_STATUS_UPDATE	Refund status update, possible statuses: `new`, `processing`, `succeeded`, `failed`.
SUBSCRIPTION_STATUS_UPDATED	Subscription status updated, possible statuses: `INCOMPLETE`, `TRIALING`, `SCHEDULED`, `ACTIVE`, `DISCOUNTED_TRIALING`, `GRACE_PERIOD`, `CANCELED`, `SUSPENDED`, `INCOMPLETE_EXPIRED`
DISPUTE_STATUS_UPDATE	Dispute status updated
PAYOUT_PAGE_STATUS_UPDATE	Payout page status updated, possible statuses: `CREATED` `PENDING` `PROCESSING` `PROCESSED` `ON_HOLD` `REFUNDED` `EXPIRED` `CANCELLED` `REJECTED`
PAYOUT_PAGE_PENDING_STATUS_UPDATE	Pending payout page sub-status updated, possible pending statuses: `PENDING_USER_CONFIRMATION`, `PENDING_USER_ONBOARDING`, `PENDING_INTERNAL_REVIEW`, `PENDING_MERCHANT_RELEASE`
CONNECT_SUCCEEDED	a member has been added to the merchant successfully
CONNECT_DELETED	a member has been removed from the merchant successfully

ℹ️

PAYMENT_CREATED event is only enabled by default for merchants onboarded after 25 Aug 2025.

FRAUD_REPORTED event is not enabled by default.

⚠️ Deprecated Events

Event Type	Description
OFFRAMP_STATUS_UPDATE	Customer offramp status was updated.
PAYOUT_STATUS_UPDATE	The payout status was updated.

🔒 Webhook Security

1. Signature Validation (Recommended)

To verify the webhook is sent by Breeze and not a third party:

Compute the HMAC-SHA256 of the raw request body using your Webhook Secret.
Compare it with the signature field in the payload.

We’ll provide a code snippet in the language of your choice in the Webhook Reference section.

2. Static IP Whitelist (Optional)

For additional security, you can restrict webhook requests to only come from Breeze’s static IPs. Contact us at [email protected] to get the current list.

🔁 Retry Policy

If your server returns a non-200 OK status code, Breeze will retry the webhook up to 10 times over a 60-minute window.
Delays between retries increase exponentially (e.g., 2s, 5s, 10s…).
Once a 200 OK status code is received, we stop retrying.

🔁 Idempotency

Webhook handlers should always be idempotent, meaning:

If you receive the same event multiple times (due to retries), your system should handle it gracefully.
Use pageId or clientReferenceId to check if you’ve already processed the event.

📘 Best Practices

Log all incoming webhooks for debugging and audit trails.
Always return 200 OK after successful processing.
Do not rely solely on client-side redirects to determine payment success.
Make your webhook handler robust against duplicate events and transient failures.