Receive important updates related to your account.
Webhooks are crucial for a successful integration with Safepay, and the only way you'll receive automatic updates about:
Events that are not triggered by a request from your side, for example when a shopper completes a payment, or when a store admin refunds a payment.
You can use webhooks to automate business processes, for example order management or downloading reports for accounting.
To manage webhooks, you must have the following user role:
To process webhooks, you need to:
1
Webhooks are HTTP callbacks sent to an endpoint on your server. Safepay requires you to use HTTPS endpoints with TLSv1.2 or TLSv1.3.
To receive webhook events, you need a server that has the following:
2
We require you to acknowledge every webhook event with a successful HTTP response status code, for example 200. If we don't receive this response within 10 seconds, for example because your server is down, all webhook events to your endpoint go to the retry queue.
When we deliver a webhook event to your server:
Verify the HMAC signature included in the webhook event payload. This is to confirm that the webhook event was sent by Safepay, and was not modified during transmission. For more information, refer to Verify HMAC signatures. If the HMAC signature is not valid, we do not recommend acknowledging the webhook event.
Store the webhook event in your database.
Acknowledge the webhook event with a successful HTTP response status code, for example 200. If an error occurs, we recommend that your server response with an error HTTP response status code.
Apply your business logic. Make sure that you acknowledge the webhook event before you apply any business logic, because an error in your business logic can prevent webhooks with important updates from reaching your system.
For information about the structure abnd content of webhooks, refer to Webhook structure and types.
3
In your Live Dashboard, enable and configure webhooks for your company account.
In your Dashboard, go to Deverlopers > Endpoints.
Select + Add an endpoint
Enter your webhook server's URL. It must be a public URL and click Create.
After you see your newly created endpoint in the list, click on the action button (three dots) and select Details from the dropdown.
From the list of available events, select all the events that you are interested in. We recommend selecting the 2.0.0 events.
Selecting multiple events means that data for each event will be sent to your endpoint. This means you must build in business logic on your side to handle all events that you select. If you are not willing to do that, you can subscribe to a single event per endpoint.
4
To test webhooks, we recommend replicating the same configurations you make on your Live Dashboard to your Sandbox Dashboard.
Once done, create a test payment and test the webhooks associated with it. Match the test payment to a webhook with the tracker.token in the payload of the webhook.
Follow the instructions in Step 3
Test webhooks in your Sandbox Dashboard. You may also create test webhook notifications using the Test Webhook API.
If you're verifying HMAC signatures, make sure that you use the HMAC key from your Live Dashboard, which is different from the HMAC key from your Sandbox Dashboard.