Webhook Event Reference

Full payload examples for every Breeze webhook event, grouped by category.

For the event envelope format, retry behavior, and signature verification, see Webhooks Overview.

ℹ️
Events marked with * are not enabled by default. See the Supported Events table for gating details.

Typical Event Sequences

Understanding which events fire — and in what order — helps you build a reliable webhook handler.

Payin 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": "page_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,
      "currency": "USD",
      "type": "CARD",
      "scheme": "AMEX",
      "last4": "0602",
      "cardType": "CREDIT",
      "bin": "377910",
      "issuer": "DBS BANK LTD",
      "threeDS": {
        "requested": true,
        "authenticationStatusCode": "Y",
        "flow": "CHALLENGE",
        "eci": "05"
      }
    },
    "source": "direct"
  },
  "signature": "afZiTJ..."
}

{
  "type": "PAYMENT_EXPIRED",
  "data": {
    "pageId": "page_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..."
}

{
  "type": "PAYMENT_ATTEMPT_FAILED",
  "data": {
    "pageId": "page_123xyz",
    "paymentId": "py_123xyz",
    "currency": "USD",
    "amount": 500,
    "status": "UNPAID",
    "errorCode": "PAYMENT_DECLINED_PROVIDER",
    "failureReason": "Payment failed. Please check your card details and balance, or try another card. If the issue persists, contact your bank or support.",
    "source": "direct"
  },
  "signature": "MfBK123xyz..."
}

{
  "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..."
}

Possible status values: new, processing, succeeded, failed.

Payout 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..."
}

Possible status values: CREATED PENDING PROCESSING PROCESSED ON_HOLD REFUNDED EXPIRED CANCELED REJECTED.

{
  "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..."
}

Possible pendingStatus values: PENDING_USER_CONFIRMATION, PENDING_USER_ONBOARDING, PENDING_INTERNAL_REVIEW, PENDING_MERCHANT_RELEASE.

Subscription & Invoice Events

{
  "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..."
}

Possible status values: INCOMPLETE, TRIALING, SCHEDULED, ACTIVE, DISCOUNTED_TRIALING, GRACE_PERIOD, CANCELED, SUSPENDED, INCOMPLETE_EXPIRED.

{
  "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..."
}

Possible status values: PENDING, PAID, EXPIRED, GRACE_PERIOD, CANCELED.

KYC & Fraud Events

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

{
  "type": "HEADLESS_KYC_STATUS_UPDATED",
  "data": {
    "id": "hkr_abc123xyz",
    "customerId": "cus_abc123xyz",
    "kycId": "kyc_abc123xyz",
    "kycStatus": "approved",
    "customerReferenceId": "<your-customer-reference-id>",
    "tier": "TIER_2",
    "rejectionReason": null,
    "createdAt": 1763717623452,
    "updatedAt": 1768901949735
  },
  "signature": "afZiTJ..."
}

Possible kycStatus values: pending, processing, approved, rejected, under_review.

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

Dispute Events

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

Crypto Events

LIQUIDATION_ADDRESS_TRANSACTION_STATUS_UPDATE fires when a customer sends crypto to their dedicated deposit address and Breeze processes the conversion and settlement.

{
  "type": "LIQUIDATION_ADDRESS_TRANSACTION_STATUS_UPDATE",
  "data": {
    "id": "lat_abc123xyz",
    "liquidationAddressId": "la_abc123xyz",
    "livemode": true,
    "status": "COMPLETED",
    "depositTransactionHash": "0xabc123...",
    "depositAmount": "100.00",
    "depositCurrency": "USDC",
    "depositNetwork": "ETH",
    "depositConfirmedAt": 1763717623452,
    "fromAddress": "0xdef456...",
    "settlementAmount": "99.50",
    "settlementCurrency": "USD",
    "settlementTransactionHash": "0xghi789...",
    "settlementConfirmedAt": 1763717700000
  },
  "signature": "afZiTJ..."
}

Possible status values: PENDING_DEPOSIT_VALIDATION, DEPOSIT_CONFIRMED, TRADE_PENDING, TRADE_EXECUTING, SETTLEMENT_PENDING, COMPLETED, FAILED, CANCELLED.

Team & Membership 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..."
}