Webhooks Overview

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. Breeze fires a webhook event on every status transition — your server does not need to poll for updates.

Event Format

Each webhook is sent as a POST request to your configured webhook URL with this JSON structure:

{
  "type": "<event-type>",
  "data": { ... },
  "signature": "<hmac-sha256-signature>"
}

type — the event name (e.g. PAYMENT_SUCCEEDED)
data — the full event payload
signature — HMAC-SHA256 of the sorted data object, used to verify authenticity (see Webhook Signature Verification)

For full payload examples for every event type, see Webhook Event Reference.

Supported Events

Event type	Description	Enabled by default
`PAYMENT_CREATED`	Payment page created; customer hasn't paid yet	Merchants onboarded after 25 Aug 2025
`PAYMENT_SUCCEEDED`	Payment completed successfully	Yes
`PAYMENT_EXPIRED`	Payment page timed out unpaid	Yes
`PAYMENT_ATTEMPT_FAILED`	A payment attempt was declined	No — contact support to enable
`REFUND_STATUS_UPDATE`	Refund status changed (`new` → `processing` → `succeeded` / `failed`)	Yes
`PAYOUT_PAGE_STATUS_UPDATE`	Payout page status changed	Yes
`PAYOUT_PAGE_PENDING_STATUS_UPDATE`	Payout page sub-status changed while in `PENDING`	Yes
`SUBSCRIPTION_STATUS_UPDATED`	Subscription status changed	Yes
`INVOICE_STATUS_UPDATED`	Subscription invoice status changed	Yes
`KYC_DATA_REQUIRED`	Breeze is requesting KYC data for a customer	Yes
`HEADLESS_KYC_STATUS_UPDATED`	Headless KYC request status changed	Yes (fires only when using the Headless KYC API)
`FRAUD_REPORTED`	Payment reported as fraudulent by card networks	No — contact support to enable
`DISPUTE_STATUS_UPDATE`	Dispute status changed	No — contact support to enable
`LIQUIDATION_ADDRESS_TRANSACTION_STATUS_UPDATE`	Crypto deposit-and-convert transaction status changed	Yes (fires only for merchants using liquidation addresses)
`CONNECT_SUCCEEDED`	A team member was added to your account	Yes
`CONNECT_DELETED`	A team member was removed from your account	Yes

Deprecated Events

Event type	Replacement
`OFFRAMP_STATUS_UPDATE`	`PAYOUT_PAGE_STATUS_UPDATE`
`PAYOUT_STATUS_UPDATE`	`PAYOUT_PAGE_STATUS_UPDATE`

Retry Policy

If your server returns a non-200 status, Breeze retries up to 10 times over a 60-minute window with exponential backoff (2s, 5s, 10s…).
Once a 200 OK is received, retries stop.
In the dashboard event log, a failed delivery appears as status: -1.

⚠️
Webhook delivery failures do not affect payment or payout status. A payment that succeeded will remain PAID regardless of webhook delivery. Always treat webhooks as a notification mechanism — if delivery fails, use the Get Payment Page endpoint to poll for current status.

Idempotency

Webhook handlers must be idempotent — the same event may be delivered more than once due to retries. Use pageId or clientReferenceId to detect duplicates before processing.

Security

Signature verification (recommended): Compute HMAC-SHA256 of the sorted data object using your webhook secret and compare against the signature field. See Webhook Signature Verification for code examples in Node.js, Python, PHP, and Java.

Static IP allowlist (optional): Contact [email protected] to get Breeze's static IPs if you want to restrict webhook sources at the network level.

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 handler robust against duplicate events and transient failures.