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:

POST /webhook/register

Authorization
x-api-key string (header)

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

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:

{
  "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.

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 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.