Skip to main content

Register Webhook

Register a URL with Vaayu so your application can receive webhook notifications about transaction activity.

Endpoint

POST /webhook/register

Authentication

Include your Vaayu API key in the X-API-Key header. The webhook configuration is associated with the authenticated merchant’s API key.

Request body

Example:
Use an endpoint reachable by your hosted Vaayu server. A local development URL may require a secure tunneling service.

Example request

Example response

The response reflects the current endpoint implementation. Treat webhook_secret as sensitive: store it securely and do not expose it in client-side code, logs, or public repositories. Verify signatures only when your webhook sender signs the payload according to your configured signature scheme.

What happens after registration?

  1. Vaayu stores the webhook URL for the authenticated API key.
  2. Vaayu can send configured event notifications to that URL.
  3. Your endpoint should validate incoming signatures when signing is enabled, process events safely, and return a successful HTTP response promptly.
  4. Your endpoint should tolerate duplicate deliveries because retries may occur.
Registering a webhook does not itself send a test event.

Security recommendations

  • Use HTTPS for publicly hosted webhook endpoints.
  • Validate submitted webhook URLs and prevent requests to private or internal network addresses.
  • Keep the webhook secret private.
  • If signatures are used, verify them against the raw request body using the documented signing scheme.
  • Make event processing idempotent so duplicate deliveries do not cause duplicate business actions.
  • Avoid returning a webhook secret on routine re-registration; expose it only when initially created or explicitly rotated.

Common errors

Actual status codes depend on the deployed API implementation.