Webhooks

A webhook can be configured to listen to users’ events and log them for analytics and re-engagement purposes.

This feature is opt-in and is configured only when a partner requests for it to be enabled. This supports use cases like getting real-time payment status and related details after bill payment is done by customer.

Pre-requisites

You need to do the following to configure a Setu provided webhook—

Share the webhook URL. A URL that can accept JSON data over POST.
API Key (optional)—It can also be generated by Setu, for you.
Take steps to handle the notification

This step requires setting up and sharing a webhook URL to Setu which is capable of receiving the transaction notifications. The URL to setup this webhook must be shared with Setu via email to billpay.support@setu.co.

Handle the notification

The notification consists of body an authentication header as well as a body/payload. The authentication header will be sent as X-BILL-WEBHOOK-API-KEY. The value for the same shall be communicated over email.

Handling Retries

When Setu sends a user event webhook (for example, bill_payment_success, bill_fetch_failure, bill_collection_failure, bill_payment_failure, bill_payment_refunded, bill_fetch_success, dispute_raised, dispute_status_change) to your endpoint, a 2xx HTTP response is expected to acknowledge successful receipt. If the endpoint responds with a non-success status code (4xx or 5xx) or fails to respond, Setu retries delivery automatically:

Retries: retries with exponential backoff for upto 5 times
Retry trigger: Any response other than 2xx or a failed connection
After all retries fail, delivery is considered unsuccessful. To avoid unnecessary retries, ensure your endpoint returns proper 2xx status codes.

Best practices: process and acknowledge webhooks quickly to prevent timeouts and implement idempotency to safely handle potential duplicate deliveries caused by retries.

List of notifications

The following events are supported in the bill payment journey—

bill_fetch_success
bill_fetch_failure
bill_payment_success
bill_payment_failure
bill_collection_failure
bill_payment_refunded
dispute_raised
dispute_status_change

Below are the parameter tables and sample payloads for the listed events. Note that we may add additional parameters at a later stage. However, we will ensure backwards compatibility and no keys will be removed.

All the values in the response payload are strings

Pre-requisites

Share the webhook URL

Handle the notification

Handling Retries

List of notifications

<code>bill_fetch_success</code>— Notification when bill-fetch request is successful

<code>bill_fetch_failure</code>— Notification when bill-fetch request is not successful

<code>bill_payment_success</code>— Notification when bill-payment request is successful

<code>bill_payment_failure</code>— Notification when bill-payment request is not successful

<code>bill_collection_failure</code>— Notification when bill-collection from the user's account is not successful

<code>bill_payment_refunded</code>— Notification when bill-payment has to be refunded. This event is invoked when bill-payment request to BBPS has failed, after collection of funds from the user.

<code>dispute_raised</code>— Notification when dispute/complaint is raised from the user

<code>dispute_status_change</code>— Notification when the status of a dispute has changed

On this page