Introduction

This document provides details on the webhook functionality of the Payment API. Webhooks are HTTP callbacks that occur when certain events happen in the system. They allow your application to receive real-time notifications about events, such as successful payments, failed transactions, etc.

How To Use Webhook

• Configure a webhook listener for your app and then create a webhook and subscribe it to the transaction event that you need.

Webhook Endpoints

A webhook URL is simply a POST endpoint that a resource server sends updates to parse, request and return.

// Using Express
app.post('/mywebhookurl', function(req, res) {
  // Retrieve the request's body
  const event = req.body;
  
  // Do something with event
  res.send(200);
});

Supported Events

Payload Format

Webhook payloads are JSON objects containing information about the event. Below is an example payload for a payment success event:

Authentication

All webhook requests are authenticated using HMAC-SHA256 signatures. Each request includes a X-Signature header containing the HMAC-SHA256 signature generated using your secret key.

Handling Webhooks

1. Receive the webhook payload from the Payment API.
2. Verify the X-Signature header using your secret key.
3. Parse the JSON payload to extract event details.
4. Process the event according to your business logic.
5. Respond with a 200 OK status code to acknowledge receipt of the webhook.

Retry Mechanism

If your endpoint fails to respond with a success status code (2xx), the Payment API will retry sending the webhook payload with exponential backoff for up to 5 times.

Testing

You can test webhook functionality using the staging environment and the provided staging endpoint. Use test payments and subscriptions to trigger different webhook events and verify your application's handling of each event.

Conclusion

Implementing webhooks allows your application to react to payment events in real-time, enabling better user experience and operational efficiency. If you have any questions or need assistance, please contact our support team at [email protected].