# 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) {% tabs %} {% tab title="Canada" %} ```json { "Type": "Invoice", "Event": "Created", "Data": { ... } } ``` {% endtab %} {% tab title="US" %} ```json { "Type": "Transaction", "Event": "Updated", "Data": { ... } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **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. {% endhint %} **Event**
EventDescriptionAvailability
CreatedEntity was createdInvoice, Subscription, Product, Tax Rate, Common Fee
UpdatedEntity was updated on some mannerInvoice, Subscription, Product, Tax Rate, Common Fee
DeletedEntity was deletedProduct
StatusChangeEntity had it's status changedInvoice, Subscription, Product, Tax Rate, Common Fee
CompletedEntity was ready to useInsights
FailedEntity was not ready to useInsights
{% hint style="info" %} **NOTE** For now, transactions and user entities does not posses events to be associated with {% endhint %} **Type**
TypeDescription
UserIndicates the webhook call is for a user status change
TransactionIndicates the webhook call is for a transaction status change
CustomerIndicates the webhook call is for a customer account status change
Recurrent TransactionIndicates the webhook call is for a recurrent transaction creation
ProductIndicates the webhook call is for a product event
InvoiceIndicates the webhook call is for a invoice event
SubscriptionIndicates the webhook call is for a subscription event
TaxRateIndicates the webhook call is for a tax rate event
CommonFeeIndicates the webhook call is for a common fee event
InsightsIndicates the webhook call is for a insights event
{% tabs %} {% tab title="Canada" %}
TypeDescription
UserIndicates the webhook call is for a user status change
TransactionIndicates the webhook call is for a transaction status change
CustomerIndicates the webhook call is for a customer account status change
Recurrent TransactionIndicates the webhook call is for a recurrent transaction creation
ProductIndicates the webhook call is for a product event
InvoiceIndicates the webhook call is for a invoice event
SubscriptionIndicates the webhook call is for a subscription event
TaxRateIndicates the webhook call is for a tax rate event
CommonFeeIndicates the webhook call is for a common fee event
InsightsIndicates the webhook call is for a insights event
{% endtab %} {% tab title="US" %}
TypeDescription
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
{% endtab %} {% endtabs %} The webhook payload uses the same JSON format as the responses for the get [User](https://docs.zumrails.com/users#get-a-specific-user), [Transaction](https://docs.zumrails.com/transactions#get-a-specific-transaction), [Product](https://docs.zumrails.com/products#get-a-specific-product), [Invoice](https://docs.zumrails.com/invoices#get-a-specific-invoice), [Subscription](https://docs.zumrails.com/subscriptions#get-a-specific-subscription), Tax Rates, Common Fees and [Insights](https://docs.zumrails.com/api-reference/insights). The [Chargeback](#chargeback-webhook) webhook payload follows the JSON structure shown in the example response. {% hint style="info" %} **INFO** If you don't want to receive webhook for a specific status, then you can specify the status in the portal settings. {% endhint %} ## 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)](https://en.wikipedia.org/wiki/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: {% tabs %} {% tab title="Canada" %} {% hint style="info" %} **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. {% endhint %} {% hint style="info" %} **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. {% endhint %} {% endtab %} {% tab title="US" %} {% hint style="danger" %} **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. {% endhint %} {% hint style="danger" %} **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. {% endhint %} {% endtab %} {% endtabs %} ## 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 , changes can be made. ## Receiving users' financial institution details {% tabs %} {% tab title="Response" %} ```json { "Type": "Transaction", "Data": { ... "InteracDebtorInstitutionNumber": "999", "InteracDebtorInstitutionName": "Testing Financial Institution", "InteracDebtorFullName": "Debtor Full Name", ... } } ``` {% endtab %} {% endtabs %} 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). {% hint style="info" %} **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. {% endhint %} {% hint style="info" %} **INFO** This information might not be available for all accounts. For any questions contact our support team {% endhint %} ## Chargeback webhook {% tabs %} {% tab title="Response" %} ```json { "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" } } ``` {% endtab %} {% endtabs %} 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. | ## Card webhook {% tabs %} {% tab title="Card Issued Event" %} ```json { "Type": "CardIssued", "Event": "SentCardIssuedForPrepaidCard", "Data": { "UserId": "a128cbcc-c418-425", "Firstname": "John", "Lastname": "Doe", "Dateofbirth": "01-01-0001", "ShippingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "BillingAddress": { "AddressLine1": "123 Main Stre", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "Email": "john.doe@zumrails.com", "Phonenumber": "4161112222", "CardNo": "***********5540", "CardReferenceId": "10123123312311", "CardStatus": "Issued&inactive", "CardProgramID": "Zumrail_Test", "AvailableBalance": 100.00, "LedgerBalance": 100.00 } } ``` {% endtab %} {% tab title="Mobile Wallet OTP Event" %} ```json { "Type": "OtpNotification", "Event": "SentMobileWalletOtpForPrepaidCard", "Data": { "CreateAt": "2025-04-22T13:55:00", "OtpMessage": "123456", "OtpExpiry": "10", "UserId": "a128cbcc-c418-4250-ac54-cfa1bdab0491", "UserEmai": "john.doe@zumrails.com" } } ``` {% endtab %} {% tab title="Card Profile Change Event" %} ```json { "Type": "ProfileUpdate", "Event": "SentProfileUpdateforPrepaidCard", "Data": { "UserId": "a128cbcc-c418-425", "Firstname": "John", "Lastname": "Doe", "ShippingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "BillingAddress": { "AddressLine1": "123 Main Stre", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "Email": "john.doe@zumrails.com", "cellNo": "4161112222", "CardNo": "***********5540", "CardReferenceId": "10123123312311", "CardProgramID": "Zumrail_Test", "Language": "fr" } } ``` {% endtab %} {% tab title="Prepaid Card Onboarding Event - Under Review" %} ``` { "Type": "PrepaidCardOnboarding", "Event": "UnderReview", "EventGeneratedAt": "2025-12-19T21:25:04.3838004Z", "Data": { "UserId": "a128cbcc-c418-425", "PrepaidCardVerificationStatus": "UNDER RECIEW", "Warnings": [ "The given identify document/number has been previously verified.", "The ID type does not match with the input identity type." ] } } ``` {% endtab %} {% tab title="Prepaid Card Onboarding Event - Declined" %} ``` { "Type": "PrepaidCardOnboarding", "Event": "Declined", "EventGeneratedAt": "2025-12-19T21:25:04.3838004Z", "Data": { "UserId": "a128cbcc-c418-425", "PrepaidCardVerificationStatus": "DECLINED", "Warnings": [ "Face mismatch between document/govern,ent photo and selfie photo.", "The given identity document/number has been previously verified.", "Selfie photo is not live." ] } } ``` {% endtab %} {% endtabs %} **Event** | Type | Event | Description | | --------------------- | ----------------------------------- | ------------------------------------------------------------------- | | PrepaidCardOnboarding | Approved | Prepaid card user is ready for card issuance | | PrepaidCardOnboarding | Declined | Prepaid card user is declined | | PrepaidCardOnboarding | UnderReview | Prepaid card user is under review | | PrepaidCardOnboarding | InProgress | Prepaid card user application in progress | | PrepaidCardOnboarding | Incomplete | Prepaid card user application completed the Profile Setup step | | Cardissued | SendPrepaidCardIssued | Prepaid card is issued to the approved user | | CardActivated | SentPrepaidCardActivated | Prepaid card is activated | | CardStatusChange | SentPrepaidCardStatusChange | Prepaid card status change | | CardProfileChange | SentProfileUpdateforPrepaidCard | Prepaid card profile change | | CardProgramChange | SentPrepaidCardProgramChange | Prepaid card program change | | CardReissue | SentPrepaidCardReissue | Prepaid card is reissued | | NetworkDebit | SentNetworkDebitforPrepaidCard | Prepaid card network debit related financial transactions | | NetworkCredit | SentNetworkCreditforPrepaidCard | Prepaid card network credit related financial transactions | | NonNetwork Debit | SentNonNetworkDebitforPrepaidCard | Prepaid card non-network debit related financial transactions | | NonNetwork Credit | SentNonNetworkCreditforPrepaidCard | Prepaid card non-network credit related financial transactions | | NonNetworkDecline | SentNonNetworkDeclineforPrepaidCard | Prepaid card non-network decline related to a financial transaction | | InactiveCardFee | CardInactivityFeeforPrepaidCard | Prepaid card inactivity fee applied to the card | | OtpNotification | Sent3DSOtPforPrepaidCard | Prepaid card online transaction triggered a 3DS OTP request | | OtpNotification | SentMobileWalletOtpforPrepaidCard | Prepaid card mobile wallet provisioning triggered an OTP request |