Transaction Notifications

Our webhooks provide real-time notifications for completed transaction and token events. You can configure webhooks to receive notifications for specific events, such as when a sale transaction is completed or a token is created. Each event type is separate, so you can choose to subscribe to only the events you want to receive notifications for. See the individual endpoint documentation for more details about when each event is triggered.

Each event is sent as a POST request to the endpoint URLs you configure, and each endpoint chooses which event types it subscribes to. The request body will contain a JSON payload with the details of the event.

Webhooks are delivered through Svix, our webhook delivery provider. When a delivery fails, Svix retries it automatically on an exponential backoff schedule over roughly the following day; endpoints that keep failing may be disabled automatically. Failed deliveries can be inspected and replayed manually from the webhook portal.

You can subscribe to receive notifications for the following transaction events:

• sale.completed
• auth.completed
• capture.completed
• refund.completed
• void.completed

See the Token Notifications section for available token notifications.

Webhook Configuration

Endpoints are managed from the webhook portal: add one or more endpoint URLs, choose the event types each endpoint subscribes to, inspect delivery attempts, and replay failed messages. Each endpoint has its own signing secret (prefixed whsec_), shown in the portal.

Verifying signatures

Every delivery includes three headers used to verify authenticity:

• svix-id — the unique message id for this delivery
• svix-timestamp — the time the message was sent (Unix seconds)
• svix-signature — one or more space-delimited signatures, each in the form v1,<base64 signature>

The signature is an HMAC-SHA256 over the string {svix-id}.{svix-timestamp}.{raw request body}, keyed with your endpoint's signing secret (the base64-decoded portion after the whsec_ prefix). The result is base64-encoded and must match one of the signatures in the svix-signature header — multiple signatures may be present while a secret rotation is in progress.

We strongly recommend verifying with one of the official Svix libraries rather than implementing the check by hand; the libraries also enforce a timestamp tolerance that protects against replay attacks.

Note: Use the raw JSON exactly as received in the HTTP request body — no reformatting, indentation changes, or whitespace modifications.