🔔 Webhooks

Webhooks in Balad® provide a simple, automated way for our servers to notify your system about important events in near real time.

When building Balad integrations, you might want your applications to receive events as they occur in your Balad accounts, so that your backend systems can execute actions accordingly.

📋 Before Creating Webhook: Whitelisting

Required

To start receiving webhook notifications on the production environment, your Webhook Server URL must be whitelisted by the Balad® Support Team.

📌

Sandbox Testing: For the Sandbox environment, no prior whitelisting is required. You can immediately create and test your webhooks. Sandbox Testing Guide

Create your webhook in the Partner Dashboard (see steps below).

Whitelisting request is created automatically - Your webhook URL must be approved before it can receive events.

Track approval status via the Tickets Module in your Partner Dashboard.

Wait for Ops Team approval - The team will whitelist your domain for production use.

🚀 Add a Webhook (Dashboard)

Step 1 — Open Add Webhook

In Developer → Webhooks → Add Webhook, fill the form:

Name: webhook_name

URL: https://your-domain.com/

Secret: (auto-generated or paste your own, e.g. 6sujb4UuMUF7lRsoxFzQQ1HiydVn0RXj)

Events: select event/s which you wish to receive

Secret length must be 32 characters long

Step 2 — Request Whitelisting

After creating your webhook, your Webhook URL must be whitelisted before it can receive events.
Wait for the Ops Team to approve and whitelist your domain.
You can follow up and track the status via the Tickets Module in your Partner Dashboard.

📝 Event Overview and Structure (V2)

Balad generates event data to inform you of activity in your account. When an event occurs, Balad creates a new Event object. By registering webhook endpoints, your app receives these Event objects via POST requests to your server. Your backend can then trigger actions automatically.

📌 Subscribing to Events

Once your webhook endpoint is whitelisted, you can choose which events to subscribe to.

Transaction Status Updates

Receive notifications whenever a transaction changes status.

Headers

Security: Verify the signature to ensure the request originated from Balad.

X-HMAC-SIGNATURE: HMAC 256 for the minified JSON payload using your Webhook Secret.

User-Agent: "Balad Egypt"

Event Object Structure (V2)

All new webhooks use the Version 2 payload structure, which nests the transaction details within the data object.

Field	Old Name (V1)	New Name (V2)	Description
Event ID	`id`	`id`	A unique identifier for this specific webhook event.
Event Type	`eventType`	`event_type`	The type of event (e.g., `994019` for status updates).
Timestamp	`timestamp`	`timestamp`	The date and time the event was generated.
Version	`version`	`version`	The version of the payload structure. Currently `2`.
Payload	N/A	`data`	The container object for the transaction status details.

Example Event Payload (V2)

This example shows a rejected transaction using the new V2 format, which includes the failureDetails object for granular reasons.

{
  "id": "180377",
  "eventType": "994019",
  "timestamp": "25-Nov-2025 08:52:02 AM",
  "version": "2",
  "data": {
    "referenceNumber": "Ref-1764060698635",
    "transactionStatusCode": 17,
    "transactionStatusDescription": "Bank Compliance Rejected",
    "reason": "Bank-failure due to sandbox suffixes rules",
    "failureDetails": {
      "category": "COMPLIANCE_RESTRICTION",
      "code": "CMP_001",
      "message": "Rejected due to AML / sanctions screening",
      "additionalInfo": ""
    }
  }
}

Webhooks

🔔 Webhooks#

📋 Before Creating Webhook: Whitelisting#

🚀 Add a Webhook (Dashboard)#

📝 Event Overview and Structure (V2)#

📌 Subscribing to Events#

Event Object Structure (V2)#

Example Event Payload (V2)#

🔔 Webhooks

📋 Before Creating Webhook: Whitelisting

🚀 Add a Webhook (Dashboard)

📝 Event Overview and Structure (V2)

📌 Subscribing to Events

Event Object Structure (V2)

Example Event Payload (V2)