Configure Webhooks
Paysafe’s instant, real-time notifications are Webhooks that inform you of all the status updates. A Webhook is an HTTP callback which is triggered when an event takes place. You can specify the destination URL in the form of an HTTP request when creating a Webhook. Notifications are delivered to this URL on your server based on event occurrences.
Why use Webhooks?
You can use Webhooks whenever you want to know and act upon event occurrences such. You can configure your Webhook subscription for events such as `payment failed, Payment cancelled, and so on, and notify yourself for these events. For a detailed list of supported Webhook events, refer to the section “List of supported webhook events and topics”
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
{
"accountId": "1009688230",
"id": "a49ba790-9cc5-4502-9f4a-dccc72460cf1",
"merchantRefNum": "2e568da7c4643d567d60",
"amount": 500,
"usage": "SINGLE_USE",
"executionMode": "SYNCHRONOUS",
"currencyCode": "USD",
"type": "PAYMENT_HANDLE",
"status": "COMPLETED",
"paymentType": "CARD"
}
See Webhooks Events to view a list of events in the API that can trigger webhooks.
Paysafe strongly recommends Webhooks for Payment Methods that require a “redirect” flow, such as Skrill, Paysafecard, Paysafecash, iACH, Paypal, Interac, VIP Preferred, Play+(Sightline).