Webhook Listener API Documentation

A Webhook Listener is a server-side endpoint that listens for incoming HTTP POST notifications triggered by payment events. These notifications are sent to the `webhook_url` you configure during the payment initiation process.

Key Features

Real-Time Notifications: Receive instant updates for payment events (e.g., success, failure).
Secure Communication: Validate the eazzpay-client-secret header to ensure notifications are authentic.
Supports Multiple Payment Methods: Handles notifications from mobile financial services (MFS) like Bkash, Cellfin, Rocket, Nagad, Upai, and others.

Webhook Payload Example

When a payment event occurs, the following JSON payload will be sent to your configured webhook_url:

{
  "amount": "100.00",
  "payment_method": "BKASH",
  "sender_number": "01311111111",
  "transaction_id": "TRX12345",
  "reference": "ORDER123",
  "date_time": "2023-11-27 12:34:56"
}

Field Descriptions

Field	Type	Required	Description
`amount`	string	Yes	The payment amount. Example: `"100.00"`.
`payment_method`	string	Yes	Mobile financial service used for payment. Accepted values: BKASH, CELLFIN, ROCKET, NAGAD, etc.
`sender_number`	string	Yes	Mobile number of the sender. Example: `"01311111111"`.
`transaction_id`	string	Yes	Unique transaction ID. Must be between 6-15 characters. Example: `"TRX12345"`.
`reference`	string	No	Optional customer-provided reference. Must be between 6-15 characters. Example: `"ORDER123"`.
`date_time`	string	Yes	Date and time of the transaction in `YYYY-MM-DD HH:mm:ss` format.

Validating Webhook Notifications

To ensure security, the request headers will include an eazzpay-client-secret. Validate this header against your stored secret to confirm authenticity.

Header Example

{
  "eazzpay-client-secret": "your-eazzpay-client-secret"
}

Validation Steps

Compare the eazzpay-client-secret from the headers with your stored secret.
If the secret matches, process the payload.
Respond with a 200 OK status to acknowledge the notification.

Example Requests

const express = require('express');
const app = express();
const EAZZPAY_CLIENT_SECRET = 'your-eazzpay-client-secret';
 
app.use(express.json());
 
app.post('/webhook', (req, res) => {
  const eazzpayClientSecret = req.headers['eazzpay-client-secret'];
 
  // Validate client secret
  if (eazzpayClientSecret !== EAZZPAY_CLIENT_SECRET) {
    return res.status(403).send('Invalid client secret');
  }
 
  // Process the payload
  const payload = req.body;
  console.log('Received webhook payload:', payload);
 
  // Send a success response
  res.status(200).send('Webhook received');
});
 
app.listen(3000, () => {
  console.log('Webhook listener is running on port 3000');
});

Testing Webhooks

Use tools like Postman or Webhook.site to test your webhook listener.
Ensure your server responds with 200 OK for successful requests.
Log all incoming payloads for debugging and monitoring purposes.

Notes

Always validate the eazzpay-client-secret to ensure the request is authentic.
Retry logic may apply if the server does not respond with 200 OK.
Test the webhook integration in a sandbox environment before deploying to production.