Webhooks

The goal of the webhooks is to give your organization a real time update on the status and events of users, transactions, products, invoices, subscriptions, taxes and common fees so you can automate your next call to action depending of the status of the payments or the occurrence of events.

To enable webhooks you have to open the settings page using the portal.

When a URL is defined, Zūm will send a POST request each time there is a status change or event triggered for:

• Users (only available for customers)

• Transactions (only available for customers)

• Customers (only available for partners)

• Recurrent Transaction (only available for customers)

• Products (only available for customers)

• Invoices (only available for customers)

• Subscriptions (only available for customers)

• Taxes (only available for customers)

• Common Fees (only available for customers)

• Insights (only available for customers)

• Chargeback Action (only available for customers)

Canada

  {
      "Type": "Invoice",
      "Event": "Created",
      "Data": {
          ...
      }
  }

US

  {
      "Type": "Transaction",
      "Event": "Updated",
      "Data": {
          ...
      }
  }

INFO

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	Availability
Created	Entity was created	Invoice, Subscription, Product, Tax Rate, Common Fee
Updated	Entity was updated on some manner	Invoice, Subscription, Product, Tax Rate, Common Fee
Deleted	Entity was deleted	Product
StatusChange	Entity had it's status changed	Invoice, Subscription, Product, Tax Rate, Common Fee
Completed	Entity was ready to use	Insights
Failed	Entity was not ready to use	Insights

NOTE

For now, transactions and user entities does not posses events to be associated with

Type

Type	Description
User	Indicates the webhook call is for a user status change
Transaction	Indicates the webhook call is for a transaction status change
Customer	Indicates the webhook call is for a customer account status change
Recurrent Transaction	Indicates the webhook call is for a recurrent transaction creation
Product	Indicates the webhook call is for a product event
Invoice	Indicates the webhook call is for a invoice event
Subscription	Indicates the webhook call is for a subscription event
TaxRate	Indicates the webhook call is for a tax rate event
CommonFee	Indicates the webhook call is for a common fee event
Insights	Indicates the webhook call is for a insights event

Canada

Type	Description
User	Indicates the webhook call is for a user status change
Transaction	Indicates the webhook call is for a transaction status change
Customer	Indicates the webhook call is for a customer account status change
Recurrent Transaction	Indicates the webhook call is for a recurrent transaction creation
Product	Indicates the webhook call is for a product event
Invoice	Indicates the webhook call is for a invoice event
Subscription	Indicates the webhook call is for a subscription event
TaxRate	Indicates the webhook call is for a tax rate event
CommonFee	Indicates the webhook call is for a common fee event
Insights	Indicates the webhook call is for a insights event

US

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 uses the same JSON format as the responses for the get User, Transaction, Product, Invoice, Subscription, Tax Rates, Common Fees and Insights.

The Chargeback webhook payload follows the JSON structure shown in the example response.

INFO

If you don't want to receive webhook for a specific status, then you can specify the status in the portal settings.

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: https://github.com/danharper/hmac-examples

Canada

INFO

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 MAKING SURE THE PAYLOAD IS IN UTF-8 CHARSET,

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.

US

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 anything specific in our retry policy, don't hesitate to talk with us, to [e-mail], changes can be made.

Receiving users' financial institution details

Response

{
    "Type": "Transaction",
    "Data": {
        ...
        "InteracDebtorInstitutionNumber": "999",
        "InteracDebtorInstitutionName": "Testing Financial Institution",
        "InteracDebtorFullName": "Debtor Full Name",
        ...
    }
}

For Interac transactions, you can now receive the end users' financial institution name and financial institution number which was used to complete the Interac requests. To receive this information, make sure you have configured the InteracSettledIntoWallet webhook event. (You can set this event by going to settings > webhook and API settings > Interac status change).

NOTE

In some cases the bank may return the same input provided on Zum Rails and not the name on the user’s account for the parameter "InteracDebtorFullName". This will result in the transaction going through successfully even when the name might not be a match. This is rare and the banks are working to improve on their end.

INFO

This information might not be available for all accounts. For any questions contact our support team

Chargeback webhook

Response

  {
      "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.

Event

Event	Description
AcceptedByUser	Chargeback was accepted by user.
AcceptedByDefault	Chargeback was accepted past due date.
Disputed	Chargeback was disputed by user.