Skip to content
TatvaPay
Docs menu· Webhooks

Webhooks

Next

Signed events TatvaPay sends to your servers, with retries and a delivery log.

Coming next. Webhooks are delivered from the sandbox today. Partner webhooks into TatvaPay come with the payment partner.

Add an endpoint in Developers → Webhooks (or POST /v1/pay/webhooks with an API key). You get a signing secret (whsec_…) once. Each delivery is a POST of JSON:

{"id": "whd_…", "type": "intent.settled", "created_at": "…", "data": {"id": "pi_…", "status": "settled"}}

Events

mandate.active, mandate.paused, mandate.revoked, intent.requires_approval, intent.settled, intent.failed, intent.rejected, refund.requires_approval, refund.processing (a partner accepted it and will confirm later), refund.succeeded, refund.failed, refund.rejected, forex.submitted, forex.booked, forex.rejected, forex.paid, forex.completed. Platforms (sandbox) also get submerchant.status, order.created, order.paid, order.failed, order.cancelled, order.expired, order.refund_failed, refund.processed, settlement.processed, fee.instalment_paid and fee.instalment_failed (Platforms). An endpoint with no events chosen gets all of them.

Verify every delivery

TatvaPay-Webhook-Id: whd_…
TatvaPay-Webhook-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>." + raw body)>

Check the HMAC over the raw body with your secret, and refuse a t more than 5 minutes old:

from tatvapay.webhooks import verify_webhook
ok = verify_webhook(secret, raw_body, request.headers["TatvaPay-Webhook-Signature"])
import { verifyWebhook } from "@tatvapay/sdk";
const ok = await verifyWebhook(secret, rawBody, request.headers.get("TatvaPay-Webhook-Signature") ?? "");

Retries and the delivery log

A 2xx answer is delivered. Anything else is retried six times with doubling backoff (from 30 seconds), then marked failed. The delivery log in the app shows each attempt's status (not the payload) and lets you resend. Rotating the secret takes effect at once. Endpoints must be reachable on the public internet: private addresses are refused.

Last updated 2 October 2026

Something unclear or wrong? Tell us