Webhooks

Webhooks allow you to receive real-time notifications about events that happen in your integration with our payment platform. They are a powerful way to keep your application updated when specific actions occur, such as successful payments, failed transactions, or refunds.

How Webhooks Work

1. Event Occurs: A specific event takes place, such as a successful payment or a failed transaction.
2. Notification Sent: We send a HTTP POST request to the webhook URL you configured.
3. Your Server Responds: Your server processes the request and returns a 200 HTTP status code to acknowledge receipt of the webhook.
4. Action Taken: Based on the event data received, you can trigger actions such as updating your database, sending notifications, or providing customer updates.

Setting Up Webhooks

Follow these steps to set up webhooks for your integration:

Step 1: Configure Your Webhook URL

Log in to your dashboard and navigate to the Settings > API Keys > Wehhook URL section. Enter the URL of your server endpoint where you want to receive webhook notifications. Ensure this endpoint is accessible and secure (use HTTPS).

Step 2: Handle Webhook Events on Your Server

Create a server endpoint that can process incoming webhook payloads. This endpoint should:

• Parse the JSON payload.
• Verify the authenticity of the webhook.
• Handle the event appropriately.

Step 3: Verify Webhook Authenticity

To ensure that the request is from us, verify its authenticity by checking the signature provided in the webhook headers. Use the secret key available in your dashboard to validate the signature.

Step 4: Respond to the Webhook

Your server must respond to the webhook request with a 2xx HTTP status code. This tells our platform that you have successfully received the event. Failure to do so may result in retries of the webhook delivery.

Example Payload

Here is an example of a webhook payload for a successful payment:

{
  "event": "payment.success",
  "data": {
    "transaction_id": "123456789",
    "amount": 5000,
    "currency": "NGN",
    "status": "success",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    }
  }
}

Event Types

Below are some common webhook events:

Event Name	Description
payment.success	Triggered when a payment is successful.
payment.failed	Triggered when a payment fails.
refund.processed	Triggered when a refund is processed.
transfer.success	Triggered when a transfer is successful.
subscription.renew	Triggered when a subscription is renewed.

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.