Webhooks
The goal of the webhooks is to give your organization a real time update on the status of transactions so you can automate your next call to action depending of the status of the payments or the occurrence of events.
To enable webhooks, open Settings > Webhook & API Settings in the portal. When a webhook URL is defined, Zūm will send a POST request each time there is a status change or event triggered for:
- Transactions (only available for customers)
- Customers (only available for partners)
- Chargeback Action (only available for customers)
- Sample Response
info
The payload has a property Type to indicate the entity the webhook status
change is coming from.
Types
| Type | Description |
|---|---|
| Transaction | Indicates the webhook call is for a transaction status change |
| Customer | Indicates the webhook call is for a customer account status change |
| Chargeback Action * | Indicates the webhook call is for a transaction chargeback status change |
The webhook payload has the same JSON format for the GET transaction endpoint.
* The webhook payload for Chargeback has the JSON format as indicated in the response.
info
If you want to receive webhook for a specific event, then you can specify the event in Webhook & API Settings page in the portal.
Verifying authenticity#
When Zūm Rails sends data to external services (e.g. when triggering a webhook to a service owned by you), the payload will be authenticated with a hash-based message authentication code (HMAC).
The key used to create the HMAC is your Webhook Secret, and you verify it by running the algorithm yourself with the payload and the key to re-create the HMAC. Your Webhook Secret can be found in the portal under your settings.
The signature is always sent with the webhook in a header named zumrails-signature
You can verify the authenticity of the webhook response by using HMAC. The HMAC verification process is as follows:
- You receive a POST request via the webhook
- Your app computes a signature based on payload received, using your Webhook Secret
- You verify that your signature matches the zumrails-signature in the request
Here are the steps to validate a request coming from Zūm Rails. You'll need the zumrails-signature sent by the webhook and your key (which is your Webhook Secret):
- Retrieve the zumrails-signature header
- Retrieve json body of the request. Make sure you are not adding any new spaces or formats.
- Using HMAC SHA256 implemented in your programming language, calculate the signature in your side. The body is the payload and the secret is your Webhook Secret.
- Compare your hash with the value provided under the zumrails-signature in the request, they should match.
A few examples on how to calculate HMAC in different languages can be found here: https://github.com/danharper/hmac-examples
caution
When generating the signature, make sure you are using the body received in the payload, as it is. Some languages might add spaces or tabs.
caution
We calculate the signature when the payload is in UTF-8 charset, so make sure it is the same on your side, or else the signatures won't match.
Retry in case of failure#
In the event of a failure to deliver the webhook (!= 200) we will try again 3 times every 5 minutes in sandbox. In production we will retry 5 times every 60 minutes.
If you have questions about anything specific in our retry policy, reach out to support@zumrails.com.
Chargeback webhook#
- Response
The payload has a property Type to indicate to each entity the webhook status change is coming from and also a property called Event that indicates the type of event that trigger the webhook.
Event
| Event | Description |
|---|---|
| AcceptedByUser | Chargeback was accepted by user. |
| AcceptedByDefault | Chargeback was accepted past due date. |
| Disputed | Chargeback was disputed by user. |