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 URL you specify in your webhook configuration, and events can all be sent to the same URL or to different URLs (per event type). The request body will contain a JSON payload with the details of the event.

Our system will attempt to deliver event notifications to your configured destination multiple times. When a notification request fails to deliver, the system will retry failed requests with an exponential backoff strategy. If the request continues to fail after multiple attempts, the event will be marked as failed and will not be retried again.

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

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

See the Token Notifications section for available token notifications.

Webhook Configuration

Before configuring webhooks, a shared secret value must be exchanged. This secret is a random string generated by us and securely shared with you. It must be kept confidential and never exposed publicly.

Incoming webhook requests will include an x-fsk-wh-chksm header containing an HMAC-SHA256 hash of the request body, used to verify authenticity.

The hash is generated by applying HMAC-SHA256 to the raw webhook request body, using the shared secret as the key. The result is encoded as a lowercase hex string.

Example

Given the following webhook request body (partial example shown):

{"event":{"id":"evt_01JSQ33SMQKET4DMRV46W9WY84","type":"sale.completed","timestamp":"2025-04-07T20:03:05Z"}}

And using secret_value as the shared secret, the HMAC-SHA256 hash is calculated with:

HMAC_SHA256(
  key = "secret_value",
  message = '{"event":{"id":"evt_01JSQ33SMQKET4DMRV46W9WY84","type":"sale.completed","timestamp":"2025-04-07T20:03:05Z"}}'
)

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

The resulting lowercase hex-encoded hash:

ef9da49d5b58f721897e6b0519ad53c0dae1478d3458134a49d86faa70dfd7b7

The value in the x-fsk-wh-chksm header must match this hash exactly.