Configuring Webhooks
Paysafe’s instant, real-time notifications are webhooks that provide you with status updates. A webhook is an HTTP callback triggered when an event takes place. When creating a webhook, you can specify the destination URL on your server in the form of an HTTP request. Notifications are delivered to this URL based on event occurrences.
Why use Webhooks?
You can use webhooks whenever you want to know about and take action based on specific events. You can set up your webhook subscription to receive notifications about events such as "payment failed", "payment canceled" and so on. For a detailed list of supported webhook events, see Webhook Events.
Webhook Request Details
When you configure your webhooks subscription, events are created and sent asynchronously as they occur. Paysafe notification messages are POST requests that carry a JSON-encoded payload along with the HTTP headers. You need to use both – the header and the JSON string – to consume a webhook. These payloads have minimum details about the triggered event. Paysafe returns links to the corresponding API resource. You can use this to find detailed information on a resource that has changed the state. To configure webhooks, open a service request in the Business Portal.
Webhook Headers
HTTP headers are useful when consuming a webhook request. Among many HTTP headers, Paysafe also includes a webhook signature header that you can use to verify the webhook.
Webhook Signature
The webhook notification contains a signature header calculated using the following algorithm:
digest = HMAC_SHA256 (hmacKey, UTF 8 string containing the JSON webhook request body)
signature = base 64 (digest)
The code receiving the webhook needs to repeat this algorithm and compare the value generated with the value received in the header.
Example Header:
Signature: UMaQ4h635wUc4hp60Z5ASBC/5UtqKybAldOkLv6ngc0=
Webhook Payload
A webhook payload contains information about the event that occurred. It has _links to the corresponding resource that triggered the event. The payload also includes attributes such as timestamp, the topic of the event and the id of the resource.
Example Webhook Payload
{
"type": "SCHEDULED_PAYMENT_COMPLETED",
"scheduledPayment": {
"id": "84bdf715-c033-4716-8bd0-937690adbca0",
"amount": 10,
"accountId": "1000052704",
"paymentType": "CARD",
"scheduledTime": "2024-04-27T13:01:33Z",
"executionStage": "LAST_SCHEDULED_PAYMENT",
"planId": "f2da97ec-c541-486e-9000-38a02313576a",
"subscriptionId": "f3fbdce6-1714-497d-9fcd-b158c0b32d0e",
"processedPaymentDetails": {
"id": "542bbb7f-3bc7-4681-9efa-996a71c520de",
"txnTime": "2024-03-27T13:02:03Z",
"status": "COMPLETED",
"merchantRefNum": "84bdf715-c033-4716-8bd0-937690adbca0"
}
},
"eventName": "SCHEDULED_PAYMENT_COMPLETED"
}
For a list of events in the API that can trigger webhooks, see Webhooks Events.