Introduction

Webhooks allow the Merchant to track events happening in Paysafe Embedded wallet. The following object changes can be tracked using webhooks.

It is the Merchant's responsibility to:

• expose API endpoints for webhook handling
• configure the webhook root URL with Paysafe
• ensure the availability of the endpoints to receive the webhooks

Getting started

In order to start receiving notifications the URL for each event type should be configured. As well as http statuses that need to trigger the retry mechanism described below.

All notifications can be signed before sending using HMAC. In order to turn on HMAC signing, the secret, used for signing, should be communicated and set. More about HMAC signing you can find in the section Webhook signature down bellow.

Supported events

The Webhooks service supports multiple types of events related to various aspects of customer's activity:

• Customer restrictions - Events related to any changes in restriction status of a customer. Contain information about restriction name, restriction reason and required actions.
• Transactions - Events related to any changes in restriction status of a customer. Contain information about restriction name, restriction reason and required actions.
• Accounts - This event is used to track IBAN assignments.
• Payment Instruments - Events related to all changes in payment instruments of a customer.
• Kyc verifications - Know Your Customer verification status updates for customers.
• PEP/Sanctions screening - Events that reflect customer's status after PEP and Sanctions screening.
• Payment Handle - The webhook is sent when there's an update on the Payment Handle. The eventType signifies the change that occurred.

Retry mechanism

In case event is not delivered the retry mechanism is involved. Webhooks service supports infinite retry mechanism with configurable timeout. Events are retried for multiple HTTP response statuses that can be configured as well. The retry is triggered on the event sending step.

Error scenarios

In case of any error during the event processing, the event is stored in the system.

For any error during sending the event, the event is retried according to the retry mechanism. If retry is not configured the event is stored in the system.

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 encode (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=

For more details on request signing please check the Request Signing documentation.

Notifications Resend API (in development)

In cases some issue in the merchant system prevented proper event processing, events can be replayed using Notification Resend API. In order to use this feature you need to specify searching criteria to filter events, then notifications will be sent to the URLs one more time. Pay attention that events are stored in the system for one month, so the older ones could not be available for resend.

Notification Resend API allows the Merchant to request the re-sending of events that have already been sent and delivered successfully to the Merchant.