Webhooks

Webhooks allow your application to receive real-time updates about events on our payment platform such as successful payments, failed attempts, or other transaction activities.

Not the same as the callback URL

This is a server-to-server notification, separate from the browser redirect configured via callbackUrl on Initialize. See Callback URL vs Webhook URL for how the two differ.

They help you automate processes like updating order statuses, notifying users, or logging transactions when specific events occur.

How Webhooks Work

1. Event Triggered – A transaction event occurs on our platform (e.g., a successful card payment).

2. Webhook Sent – We send an HTTP POST request to the webhook URL you configured.

3. You Handle the Event – Your server processes the payload and takes appropriate action.

4. You Acknowledge – Your server responds with an HTTP 2xx status code to confirm successful receipt.

Setting Up Webhooks

Step 1: Configure Your Webhook URL

• Go to Dashboard > Settings > API Keys > Webhook URL
• Enter the URL where you'd like to receive webhook events
• Ensure the URL is publicly accessible and uses HTTPS

Step 2: Create a Webhook Endpoint

Your server should:

• Accept HTTP POST requests
• Parse the incoming JSON payload
• (Optional) Validate the webhook’s authenticity
• Perform the appropriate action (e.g., update status, notify users)

Webhook Payload Example

Webhooks only fire for successful transactions.

Example Payload

{
  "transactionId": "ZID_TRX_003",
  "amount": "7.00",
  "status": "Successful",
  "paymentMethod": "Card",
  "customerEmail": "emino@yopmail.com",
  "timestamp": "2025-09-24T01:00:02.2578189Z",
  "currency": "NGN",
  "metadata": "[{\"name\":\"name\",\"value\":\"Emino\"},{\"name\":\"age\",\"value\":\"43\"}]"
}

Field	Type	Description
transactionId	string	The transactionId you passed on Initialize
amount	number	The original amount you sent on Initialize — see Fees & Amounts for why this can differ from what the customer saw at checkout
status	string	Successful (webhooks only fire on success — see Transaction Statuses)
paymentMethod	string	Method used for payment (Card, Transfer, USSD)
customerEmail	string	Email address of the customer
timestamp	string	ISO 8601 formatted date/time of the transaction
currency	string	Currency of the transaction
metadata	string	Transaction metadata passed on initialization, JSON-stringified — JSON.parse it before reading fields. See Metadata.

Note: Each webhook event will be retried up to three times if your server does not return a successful HTTP 200 response. To confirm the status of a transaction, you may also query our API directly.

Best Practices

• Secure Your Webhook URL: Always use HTTPS to secure your webhook endpoint.
• Validate Payloads: Verify the webhook signature to ensure authenticity.
• Handle Retries: Design your server to handle duplicate webhook events gracefully.
• Log Events: Log all received webhooks for troubleshooting and audit purposes.

Testing Webhooks

• Use tools like Postman to send test webhook requests to your server endpoint.

With webhooks, you can automate many aspects of your payment processing workflow and stay updated in real time. By following the steps and best practices outlined here, you can ensure a seamless integration with our platform.