> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bilalsadasub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time transaction status updates.

Webhooks let Bilalsadasub notify your system about real-time events — primarily **transaction status updates** — so you don't have to poll the API.

## Setup

**1. Add your callback URL**

In your [dashboard](https://app.bilalsadasub.com), set your **callback URL** — a public HTTPS endpoint on your server.

**2. Receive events**

Bilalsadasub sends a `POST` request with a JSON body to that URL whenever a transaction's status changes.

**3. Acknowledge**

Respond with `200 OK` quickly. Do your processing asynchronously where possible.

> [!WARNING]
>
> Your callback URL must be configured in the dashboard for webhooks to fire.

## Example payload

```json theme={null}
{
  "status": "success",
  "request-id": "Data_12345678900",
  "response": "You have gifted 500MB to 2347013397088."
}
```

## Best practices

> [accordion] Match on request-id
>
> Always reconcile events using your unique `request-id`, not the message text.

> [accordion] Be idempotent
>
> The same event may be delivered more than once. Make sure processing the same `request-id` twice is safe.

> [accordion] Respond fast
>
> Return `200` immediately; queue heavier work so the request doesn't time out.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.