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

# Webhooks

Webhooks allow your application to receive real-time notifications when the status of a payment changes.

Instead of continuously polling the API for updates, your server receives an HTTP POST request whenever an event occurs.

## Supported Events

Currently, the API supports:

* payment.confirmed

Future events may include:

* payment.failed
* payment.pending

## Register a Webhook

Register a webhook URL using:

```text theme={null}
POST /webhook/register
```

```text theme={null}
Authorization
x-api-key string (header)
```

```text theme={null}
Request Body
{
  "webhook_url": "https://webhook.site/4e755244-2d0a-49c8-9c12-72a1c7a3b7f3"
}
```

```text theme={null}
Successful Response Body
{
  "success": true,
  "message": "Webhook registered successfully",
  "webhook_url": "https://webhook.site/4e755244-2d0a-49c8-9c12-72a1c7a3b7f3"
}
```

## Example Webhook Payload

When a payment is confirmed, your endpoint receives:

```json theme={null}
{
  "tx_hash": "ff8b020b8338037b2e6e2b8058598711b94b428c68a1f69cf163fcf36dcff586",
  "status": "confirmed",
  "amount": 9000000
}
```

## Testing Webhooks

For development, you can use a temporary webhook receiver such as Webhook.site.

1. Visit Webhook.site.
2. Copy the unique webhook URL.
3. Register it using POST /webhook/register.
4. Send a payment.
5. Watch the webhook payload appear instantly.

## Example Receiver (FastAPI)

The merchant needs an endpoint like below to receive your webhook.

```text theme={null}
from fastapi import FastAPI
app = FastAPI()
@app.post("/webhook")
def webhook(payload: dict):
   print(payload)
   return{"success": True}
```

The merchant's application must expose an HTTPS endpoint capable of receiving POST requests. During development, you can use services such as [Webhook.site](http://Webhook.site) to inspect webhook payloads without writing a webhook receiver. The above FASTAPI webhook receiver is part of merchant's application not the Vaayu API.

## Best Practices

* Respond with HTTP 200 OK as quickly as possible.
* Process webhook events asynchronously if they require significant work.
* Keep your webhook endpoint publicly accessible over HTTPS.
* In future releases, webhook requests will include a signature header so you can verify they originated from the Stablecoin Payments API.