Webhooks Overview

A webhook allows you to define an HTTP callback to which a request will be POSTed when an event occurs that you want to be notified about. You can use the merchant back office to define the notification URL and select which events you wish to be notified about. These webhooks are available for the Alternate Payments API.

This is how you create webhooks in the merchant back office:

1. Sign in to the Merchant Back Office.
2. Go to Settings > Notifications.
   
   
3. On the Alternate Payments tab, select an account from the Account drop-down list.
   
   
4. Select the events for which you want to receive callbacks for this merchant account. If you want to be notified of all events, select the Select ALL Events check box.
   
   
5. In the Endpoint field, enter the endpoint at which you want to receive the webhook, e.g., https://mywebsite.com/paymentaccepted.
   
   
   
   You can receive webhooks via HTTP or HTTPS but only HTTPS endpoints can receive a payload.
6. Click Save.
7. Make a note of the HMAC Secret Key just below the Endpoint field. This signature is used to verify the authenticity of the webhook notification and confirm that none of the data has been modified.

Note:

• You must keep your webhook signature secure.
• In order to accurately compute the Signature calculation, the HMACkey from Back-office has to be Base64 DECODED before any operation (binary – UTF8)”.

Once you have finished setting up your webhook, you can use the Test Connectivity button to make sure your callback URL is receiving calls. 

You can also use the Send Test Webhook button to test that your code to handle the webhook is working correctly.

See Testing webhooks for more information.

The webhook notification contains a signature header calculated using the following algorithm:

digest = HMAC_SHA256 (hmackey_base64_decoded, 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=

• When the status of one of your alternate payment requests changes, Paysafe immediately sends a callback to your webhooks endpoint URL to inform you of the status change.
• To acknowledge the receipt of a webhook, Paysafe expects to get an HTTP status of 200 from your endpoint. In case we receive any other HTTP status code, we will assume that you have not received the webhook and will attempt to resend it at a later time.
• If the callback for that alternate payments request status change event fails (i.e., Paysafe does not get an acknowledgment of receipt with an HTTP Status Code of 200), Paysafe will make a maximum of 10 additional attempts to send a callback to that URL until successfully received – twice daily for 5 days.
• Because Paysafe does not have a notification method to alert you when callbacks are not reaching your endpoint URL, you should make sure to test your webhooks setup and the sustained availability of your endpoint.
• All endpoint URLs should use HTTPS/SSL to ensure security.