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)
"Type": "Transaction",
"Event": "Started",
"Data": {

The payload has a property Type to indicate the entity the webhook status change is coming from.


TransactionIndicates the webhook call is for a transaction status change
CustomerIndicates 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.


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:

  1. You receive a POST request via the webhook
  2. Your app computes a signature based on payload received, using your Webhook Secret
  3. 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):

  1. Retrieve the zumrails-signature header
  2. Retrieve json body of the request. Make sure you are not adding any new spaces or formats.
  3. 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.
  4. 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


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.


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#

"Type": "ChargebackAction",
"Event": "Disputed",
"Data": {
"Id": "e5ec36c3...5445500db505",
"TransactionId": "ff116078...eee1a4f399a5",
"ReceivedDate": "2024-04-10",
"AuthorizationCode": "OK5234",
"AcquirerReferenceNumber": "1674915201620667421592979",
"ChargebackAmount": 9.9131,
"DisputeCurrencyCode": "USD",
"DisputeReasonCode": "1350",
"MemberMessageText": "Misrepresentation",
"FileId": "685221186",
"ChargebackControlNumber": "771638347",
"DueDate": "2024-04-14",
"ChargebackWorkTypeCode": "1",
"ChargebackStatus": "Disputed"

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.


AcceptedByUserChargeback was accepted by user.
AcceptedByDefaultChargeback was accepted past due date.
DisputedChargeback was disputed by user.