Webhook Setup

Configure the GrowthBnk webhook endpoint in your payment gateway dashboard so settlement updates reach your GrowthBnk account in real time — no polling required.

Overview

After you complete your payment gateway integration, settlement updates are delivered to GrowthBnk via webhooks sent by the payment gateway. To receive these events, you must register the GrowthBnk webhook endpoint in your payment gateway dashboard. Once configured, every settlement event the gateway raises is posted to GrowthBnk, verified, and reconciled against your account automatically.

Step 1: Obtain Required Details

Before configuring the webhook, make sure you have the following:

Merchant UUID — your merchant identifier in GrowthBnk.
Payment Gateway UUID — the identifier of the payment gateway configured in GrowthBnk.
An active payment gateway configuration in GrowthBnk for that gateway.

Where to find these

Your merchant_uuid and gateway_uuid are available in the GrowthBnk dashboard under your payment gateway configuration. Both are required to build the webhook URL in the next step.

Step 2: Configure the Webhook in the Payment Gateway Dashboard

Log in to your payment gateway dashboard.
Navigate to Developers → Webhooks (or the equivalent section for your gateway).
Create a new webhook endpoint.
Enter the GrowthBnk webhook URL shown below.

Webhook URL format:

Webhook URL

POST /api/v1/settlements/webhook/?merchant_uuid=<MERCHANT_UUID>&gateway_uuid=<PAYMENT_GATEWAY_UUID>

Example:

Example

https://api.growthbnk.com/api/v1/settlements/webhook/?merchant_uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&gateway_uuid=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

Both parameters are mandatory

The merchant_uuid and gateway_uuid query parameters must both be present on the URL. A webhook that is missing either parameter is rejected.

Step 3: Select Webhook Events

Enable all settlement-related events supported by your payment gateway, such as:

Settlement Created
Settlement Processed
Settlement Completed
Settlement Failed
Settlement Updated

Only settlement events are required unless otherwise specified.

Step 4: Save and Verify

Save the webhook configuration in your payment gateway dashboard. If your gateway supports sending a test webhook, trigger one to confirm that GrowthBnk successfully receives and validates the callback.

Confirm delivery

A successful test returns an acknowledgement to your gateway. If the gateway reports a failed delivery, re-check the webhook URL and that both query parameters are set correctly.

Important Notes

The merchant_uuid identifies the merchant in GrowthBnk.
The gateway_uuid identifies the configured payment gateway.
Both query parameters are mandatory.
GrowthBnk validates the webhook signature before processing the request.
Duplicate webhook deliveries are handled using idempotency, so the same event is never processed twice.
Never modify the webhook payload — GrowthBnk verifies it exactly as the gateway sends it.

Security

Keep your webhook secure

Use HTTPS endpoints only.
Keep your gateway credentials and webhook secrets confidential.
Configure only official GrowthBnk webhook URLs.
Ensure settlement events are enabled for the webhook.