Overview of Webhooks

Nium uses webhooks to notify clients' applications when any of the observable events occur. Example events include Card POS Approved, Remit Transaction Paid, and Card Wallet Funding.

Clients can provide Nium the URL of their Host endpoint to receive the webhook events from Nium Platform. Nium Platform will deliver the webhook events to the client specified endpoint.

Webhook Event Structure

Following is a sample webhook event.

curl --location --request POST 'https://<customerHost:Port>/webhook' \
-H 'content-type: application/json' \
-H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
-d '{
        "name":"Samar",
        "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2",
        "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f",
        "cardHashId":"a344b0c8-d27d-4db5-8194-aacdefb558ca",
        "cardNumber":"4001-35xx-xxxx-1950",
        "transactionCurrency":"SGD",
        "transactionAmount":"10.00",
        "transactionDate":"2020-09-29 09:24:46",
        "balanceCurrency":"SGD",
        "authAmount":"10.0",
        "walletBalance":"102.00",
        "mcc":"5499",
        "merchantName":"Frankie Tibbs",
        "merchantCountry":"IN",
        "merchantCity":"MUMBAI",
        "authCode":"114733"
        "effectiveAuthAmount":"11",
        "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2",       
        "template":"CARD_POS_APPROVED_WEBHOOK"
}'
  • The body of the webhook event generally carries just-enough details about the event. Clients are expected to use other APIs to fetch more details.
  • The body of the webhook event includes a field template to indicate the webhook event type.
  • Every webhook event includes x-request-id data element in the header. Nium Platform populates unique values in this data element for every unique webhook event (except when Nium Platform attempts to redeliver a webhook event).
  • Clients can also configure a static identifier (say x-partner-key) as part of the Client Setup, so Nium Platform can include the client specified identifier in the header of every webhook event.

Delivery

Nium supports two forms of webhook events delivery:

  • At most once (the default)
  • Retry delivery (needs to be explicitly set up).

At Most Once

The default delivery configuration supported by Nium is to deliver every webhook events at most once. An attempt will be made to deliver a webhook event. If the delivery fails (timeout or HTTP response code other than 200), Nium Platform will not retry delivering the webhook event.

Retry Delivering Webhook

Clients can work with Nium to configure the webhook events that they want Nium Platform to retry delivering, and it works as follows:

  1. For example, we have configured a 'retry' feature for the Card Wallet Funding Webhook (an event that gets triggered whenever a customer's wallet receives funds).
  2. As soon as funding is applied to a Wallet (of a Customer under your Client Setup in the Nium Platform), Nium Platform triggers the Card Wallet Funding webhook event to your registered endpoint (called Original-Attempt).
  3. If that fails for some reason, then Nium Platform makes another attempt immediately (called Retry-Attempt #1). In this retry, Nium Platform will include the same x-request-id as it sent in the Original-Attempt.
  4. If this Retry-Attempt #1 fails, then Nium Platform waits for 2 hours before trying to redeliver the webhook event (called Retry-Attempt #2).
  5. If this Retry-Attemp #2 fails, Nium Platform will wait for 2 hours and try delivering again (Retry-Attempt #3).
  6. In this manner, Nium Platform continues retrying up to 20 times (Retry-Attempt #20) with a 2-hour time gap between each retry attempt.

NOTE:

This is not the default approach available for every webhook event for clients. Clients that want this feature (i.e., the Nium Platform to retry delivering webhook events) to be enabled can reach out to their Nium representative for support. This needs to be configured at the chosen webhook event level (as part of the Client configuration) in the Nium Platform.

CAUTION:

Every re-delivered webhook event will have the same x-request-id to help clients identify if the same webhook event was already received before, and hence, they may want to ignore such duplicate webhook events.