Using Webhooks

Introduction

Webhooks provide a mechanism to receive real-time notifications when specific events occur in system. Instead of continuously polling for updates, you can subscribe to webhooks and receive an HTTP request whenever an event is triggered.

Here are sample events currently supported, full list you can check in API Reference section:

• CardNew– Triggered when a new card is issued.
• CardActivation – Triggered when a card is activated.
• AuthTransaction – Triggered when an authorization transaction occurs.
• StatusChange – Triggered when the status of a card changes.
• SMS – Triggered when an SMS notification prepared to be sent.
• 3DSOTP – Triggered when a 3D Secure OTP is generated.

Each webhook request includes a unique identifier, a timestamp, type, and relevant event details.

Webhook Payload Structure

When an event occurs, our system sends a webhook payload to your configured endpoint in JSON format. Below is example of the webhook payload:

CardNew Webhook

JSON

{  
  "id": "5c128676-c1bc-4ae8-95be-049b53f68573",  
  "type": "CardNew",  
  "timestamp": "2025-01-11T15:39:19.035Z",  
  "details": {  
    "cardId": "99985101103176340000",  
    "expiryDate": "2808",  
    "maskedPan": "99985XXXXXXX1871",  
    "clientNumber": "862347961063",  
    "cbsNumber": "7980876890876789",  
    "mobilePhone": "00971323469123",  
    "email": "[email protected]",
    "language": "Eng",  
    "shortCode": "016",  
    "productGroupCode": "ISSCREDIT",  
    "accountNumber": "9998510168946328"  
  }  
}

Configuring Webhooks

To receive webhooks, you need to provide a publicly accessible endpoint that can accept HTTP POST requests with JSON payloads.

Steps to Set Up a Webhook:

1. Create an Endpoint – Set up an API that can receive HTTP POST requests.
2. Register Your Webhook URL and Secret value – Provide your endpoint URL and secret value to our technical team.
3. Handle Incoming Webhooks – Ensure your system can process and respond to webhook notifications appropriately.
4. Verify Webhook Signature – Secure your endpoint by verifying incoming webhook requests.

Secure Webhooks

For security purposes, we use an HMAC signature to verify webhook authenticity. Each webhook request includes an X-Signature header containing the HMAC SHA-256 hash of the payload, signed with your secret key.

Verifying Webhook Requests

1. Retrieve the X-Signature header from the request.
2. Compute the HMAC SHA-256 hash of the request body using your secret key.
3. Compare the computed hash with the X-Signature value. If they match, the webhook is valid.

This ensures that the webhook request originates from our system and has not been tampered with.

Handling Webhooks Efficiently

• Respond Quickly – Acknowledge webhook delivery with a 200 OK response as soon as possible.
• Retry Mechanism – If your server is unavailable, we retry delivery multiple times with exponential backoff.
• Idempotency – Use the id field to ensure duplicate webhooks are not processed multiple times.

Testing the Webhook Payload Validation

To validate webhook payloads, you need to verify the HMAC SHA-256 signature included in the X-Signature header. Follow these steps:

1. Retrieve the Signature from Headers: Extract the X-Signature header from the incoming HTTP request.
2. Compute the HMAC SHA-256 Hash: Use your secret key to compute the HMAC SHA-256 hash of the request payload.
3. Compare Signatures: Convert the computed hash to a hexadecimal string and compare it to the signature from the header.

Java Example

The following Java example demonstrates how to validate a webhook payload:

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
public class WebhookValidator {
    // Replace with your actual secret key
    private static final String SECRET_KEY = "your_secret_key";

    public static boolean isPayloadValid(String payload, String receivedSignature) throws NoSuchAlgorithmException, InvalidKeyException {
        final SecretKeySpec keySpec = new SecretKeySpec(SECRET_KEY.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        final Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(keySpec);
        final byte[] digest = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
        final HexFormat hex = HexFormat.of();
        final String calculatedSignature = "sha256=" + hex.formatHex(digest);
        return MessageDigest.isEqual(calculatedSignature.getBytes(), receivedSignature.getBytes());
    }
}