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 Subscriptions API.
Creating a Webhook
This is how you create webhooks in the merchant back office:
- Sign in to the Merchant Back Office.
- Go to Settings > Notifications.
- On the Subscriptions and Plans tab, 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.
- In the Endpoint field, enter the endpoint at which you want to receive the webhook, e.g., https://mywebsite.com/mysubscriptions.
You can receive webhooks via HTTP or HTTPS but only HTTPS endpoints can receive a payload.
- Click Save.
- 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.
You must keep your webhook signature secure.
Once you have finished setting up your webhook, you can use the Test connectivity button to make sure your callback URL is receiving calls. Click here to see the results you should expect.
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.
Some Notes on Webhooks
- When one of your subscription events is triggered (e.g., a subscription is created), Paysafe sends a callback to your webhooks endpoint URL to inform you of the event. See Subscriptions Webhook Events for information on when the callbacks are sent.
- 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 subscription 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.