Webhooks

Webhooks allow you to receive real-time updates on payment status changes, such as successful payments, failed payments, or cancellations. This ensures that you can process payments asynchronously and take action when needed.

Setting Up Webhooks

To receive webhooks, you need to provide a valid **callback URL** where Drinah Pay can send the payment updates. This URL should be able to accept `POST` requests and process the webhook payload.

Webhook Example Payload

{
    "merchant_request_id": "12345",  // Unique ID for the merchant's request
    "checkout_request_id": "67890",  // Unique ID for the checkout request
    "status": "success",             // Status of the payment ('success', 'failed', 'pending')
    "transaction_id": "abcd1234",    // Unique transaction ID
    "amount": 1000,                  // Amount paid
    "phone": "2547XXXXXXXXX",        // Phone number used for the payment
    "payment_method": "M-Pesa"       // The payment method used
}

How Webhooks Work

Once a payment is processed, Drinah Pay will send a `POST` request to your webhook URL with the payment details. The payload will include key information such as the status of the payment, transaction ID, amount, phone number, and payment method.

Your server should process this data and update your records accordingly. For example, if the status is `success`, you can mark the order as paid. If the status is `failed`, you can notify the user and attempt a retry.

Response to Webhooks

After receiving the webhook, your server should respond with an HTTP status code to acknowledge the receipt. A `200 OK` response tells Drinah Pay that the webhook was successfully received and processed.

If your server returns a non-2xx HTTP status code (e.g., `500 Internal Server Error`), Drinah Pay will consider the webhook delivery as failed and will attempt to retry sending the webhook.

Handling Webhook Retries

Drinah Pay will automatically retry sending the webhook if it receives a non-2xx HTTP response. This ensures that your server can process the webhook even if there was a temporary issue.

You can configure the retry behavior and interval within the webhook handling logic. It's recommended to implement an idempotent webhook handler to avoid issues with duplicate processing.

Webhook Error Handling

In case of any issues with the webhook, such as invalid data or a failure to process, you should log the error and notify the administrator or retry the operation. You can also implement a manual retry mechanism to handle these errors.

Security Considerations

To ensure the security of your webhook endpoint, it's important to verify that incoming requests are from Drinah Pay. You can do this by:

Checking the `User-Agent` header for Drinah Pay's user agent string.
Validating that the request comes from Drinah Pay's IP address range.
Verifying a signature or secret key in the headers of the webhook request (if implemented).

Testing Webhooks

To test webhooks, you can use tools like [RequestBin](https://requestbin.com/) or [Webhook.site](https://webhook.site/) to capture and inspect incoming webhook requests before connecting your production server.

You can also trigger test webhooks via the Drinah Pay dashboard or by simulating payments in your development environment.

Configuring Webhooks in Drinah Pay

To configure the webhook URL in Drinah Pay, log in to your Drinah Pay merchant dashboard, navigate to the "Settings" section, and enter your webhook URL under the "Webhook URL" field.