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

# Webhooks

> Receive real-time transaction status updates.

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

## Setup

<Steps>
  <Step title="Add your callback URL">
    In your [dashboard](https://app.mysubwallet.ng), set your **callback URL** — a public HTTPS endpoint on your server.
  </Step>

  <Step title="Receive events">
    mySubwallet sends a `POST` request with a JSON body to that URL whenever a transaction's status changes.
  </Step>

  <Step title="Acknowledge">
    Respond with `200 OK` quickly. Do your processing asynchronously where possible.
  </Step>
</Steps>

<Warning>
  Your callback URL must be configured in the dashboard for webhooks to fire.
</Warning>

## Example payload

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

## Best practices

<AccordionGroup>
  <Accordion title="Match on request-id" icon="link">
    Always reconcile events using your unique `request-id`, not the message text.
  </Accordion>

  <Accordion title="Be idempotent" icon="rotate">
    The same event may be delivered more than once. Make sure processing the same `request-id` twice is safe.
  </Accordion>

  <Accordion title="Respond fast" icon="bolt">
    Return `200` immediately; queue heavier work so the request doesn't time out.
  </Accordion>
</AccordionGroup>