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 shipping rates so you can automate your next call to action depending of the status of the payments or the ocurrence 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)
- Shipping Rates (only available for customers)
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.
|Created||Entity was created||Invoice, Subscription, Product, Tax Rate, Shipping Rate|
|Updated||Entity was updated on some manner||Invoice, Subscription, Product, Tax Rate, Shipping Rate|
|Deleted||Entity was deleted||Product|
|StatusChange||Entity had it's status changed||Invoice, Subscription, Product, Tax Rate, Shipping Rate|
For now, transactions and user entitys does not posses events to be associated with
|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|
|TaxeRate||Indicates the webhook call is for a tax rate event|
|Shipping||Indicates the webhook call is for a shipping rate event|
The payload sent by the webhook has the same JSON format for the get User, Transaction, Product, Invoice, Subscription, Tax Rates and Shipping Rates.
If you don't want to receive webhook for a specific status, then you can specify the status in the portal settings.
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: 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 making sure the payload is in UTF-8 charset, so you have make the same in your side, or else it 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, changes can be made.
#Receiving users' financial institution details
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).
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.
This information might not be available for all accounts. For any questions contact our support team