Skip to main content
Payment Acceptance webhooks deliver real-time status updates to your application as payment sessions, disbursements, and mandates move through their lifecycle. Subscribe to specific event types and receive POST requests at your webhook URL whenever a status change occurs.

​
Getting started

1

Subscribe to webhooks

Set up a webhook subscription to Payment Acceptance events. This is a webhook delivery configuration, unrelated to billing subscriptions. For recurring payments, see Recurring Payments.
2

Verify

Implement signature verification in your receiver.
3

Inspect payloads

See example payloads for event shapes.

​
Event types

​
Payment session events

Subscribe to acceptance.payment_session.* events to track the full payment lifecycle:

​
Disbursement events

Subscribe to acceptance.disbursement.* events to track standalone payouts:

​
Mandate events

Subscribe to acceptance.mandate.* events to track recurring payment approvals, cancellations, and revocations. Payments authorized with a mandate fire the payment session events above.

​
Payload structure

Every webhook delivers a standard CDP envelope:
For payment session events, data.paymentSession always contains a session summary. For action-triggered events (authorization, capture, void, refund), the corresponding action detail is also present as a sibling field — data.authorization, data.capture, data.void, or data.refund. For session-level events (created, canceled), no action field is included — the paymentSession.status value is sufficient. For disbursement events, the data object contains the full disbursement resource. For mandate events, data.mandate always contains the full mandate. Approval events also include data.approval, and revocation events include data.revocation. See example payloads for complete event shapes.

​
Security

Webhook requests include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret. Always verify this signature before processing events.
X-Hook0-Signature is deprecated and will eventually be removed. Use X-Webhook-Signature going forward. Both headers are sent with identical values and use the same verification algorithm and webhook secret.
See verification for implementation details.

​
Best practices

  • Acknowledge quickly - return 200 immediately, then process in the background
  • Support concurrent delivery - your endpoint may receive multiple events at the same time
  • Verify signatures - always check X-Webhook-Signature before processing
  • Handle duplicates - use eventId for idempotent processing
  • Monitor delivery health - subscriptions can be auto-disabled after sustained delivery failures
  • Test locally first before enabling production subscriptions
If a subscription is auto-disabled due to delivery failures, fix the endpoint issue and re-enable it via the Update Subscription API.

Webhook Subscriptions

Create and manage webhook subscriptions

Verification

Verify webhook signatures

Example payloads

Complete event payload examples

Payment Sessions

Understand the payment lifecycle