Callbacks & Webhooks
The asynchronous callback pattern — correlation, acknowledgement, and idempotency.
ABDM is callback-driven: you register a bridge URL, and the gateway
delivers all asynchronous results and inbound requests there under
conventional paths (mostly on-* counterparts of the APIs you call).
The contract
Receive
The gateway POSTs JSON to https://your-bridge.example.com/<path> with
Authorization (gateway JWT), X-HIP-ID/X-HIU-ID, and a body containing
requestId, timestamp, and either a payload or an error.
Acknowledge immediately
Return 202/200 fast. Do the real work on a queue — slow webhook handlers
cause gateway retries and duplicate processing.
Correlate
resp.requestId in the callback equals the requestId you sent in the
original request. Look up your pending operation and advance its state
machine.
Deduplicate
Callbacks may be delivered more than once. Key processing on the callback's
own requestId (or transactionId) and make handlers idempotent.
Common callback families
| You call | You receive | Purpose |
|---|---|---|
| ABHA verification / link token request | on-generate-token style | Link token for care contexts |
link/carecontext | on-link | Linking confirmation |
| — (patient-initiated) | care-contexts/discover | Discovery request to your HIP |
| — (patient-initiated) | link/init, link/confirm | Patient-initiated link auth |
| — (CM) | consents/hip/notify | Consent artefact for your records |
consent/request (HIU) | consent/on-request, consents/hiu/notify | Consent lifecycle |
health-information/request | data at your dataPushUrl | Encrypted FHIR pages |
| any | on-* with error | Failure results |
Error object
Every callback can carry error: { code, message } instead of a result.
Surface these to your operations tooling — silent failures are the top
integration debugging pain.
Timeouts and retries
- If no callback arrives within your SLA window (commonly ~10–30s for
interactive flows), fail the operation in your UI and let the user retry —
with a new
requestId. - Track orphan callbacks (arriving after timeout) and reconcile rather than crash.
- Keep a callback audit log (headers + body + received-at) for certification and production debugging.
Local development
The gateway must reach your bridge URL over public HTTPS. For local dev use a tunnel (ngrok, cloudflared) and point your sandbox bridge registration at it.
cloudflared tunnel --url http://localhost:8080
# register the generated https URL as your bridge URL