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.

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

Example Payload

{
  "transactionId": 1,
  "amount": 500,
  "status": "Success",
  "paymentMethod": "Card",
  "customerEmail": "chibue@mail.com",
  "timestamp": "2025-07-22T19:59:06.02126Z"
}

Field	Type	Description
transactionId	number	Unique ID of the transaction
amount	number	Amount paid in the transaction
status	string	Transaction status (Success, Failed, etc.)
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

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.