If you are building an ABDM integration and your callback URL is not receiving requests from the gateway, you are not alone. This is the single most common problem on the ABDM Developer Forum with 8+ threads of developers stuck on the exact same issue.
The Callback Architecture
ABDM does not return data in API responses. Instead, it calls back to your registered bridge URL. Your server must be publicly accessible, handle POST requests at specific paths, and return 202 Accepted quickly.
Step 1: Register Your Bridge URL
Use the PATCH endpoint to register your public URL:
PATCH /gateway/v3/bridge/url
Authorization: Bearer <gateway_token>
{ "url": "https://your-domain.ngrok-free.app" } A 202 response means accepted. But it takes 5-15 minutes to propagate. Testing immediately will fail.
Step 2: Set Up a Stable Tunnel
Use ngrok over Cloudflare Tunnels. Free Cloudflare tunnels change URLs on restart, requiring re-registration.
ngrok http 3000 --domain=your-subdomain.ngrok-free.app Step 3: Handle All Three Path Formats
ABDM sends callbacks to inconsistent URL paths:
/v3/hip/patient/care-context/discover
/api/v3/hip/patient/care-context/discover
/api/callbacks/v3/hip/patient/care-context/discover Use a catch-all route handler that matches on path segments:
// Next.js: /api/callbacks/v3/[[...path]]/route.ts
export async function POST(req, { params }) {
const fullPath = (await params).path.join('/')
if (fullPath.includes('patient/care-context/discover')) {
// Handle discovery
}
} Step 4: V3 Discovery is Async
The most common V3 migration bug. In V1/V2, discovery was synchronous. In V3, it is asynchronous.
- ABDM calls your discovery endpoint
- Return
202 Acceptedimmediately - Call
/on-discoverwith the results asynchronously
Step 5: Use REQUEST-ID from Headers
ABDM sends requestId in the HTTP header (REQUEST-ID), not in the body:
const abdmRequestId = req.headers.get('REQUEST-ID') || ''
{ response: { requestId: abdmRequestId } } Step 6: Add Logging Middleware
export async function middleware(req) {
if (req.method === 'POST') {
console.log(`[CALLBACK] POST ${req.nextUrl.pathname}`)
}
return NextResponse.next()
} Complete Checklist
- Bridge URL registered (202 response)
- Waited 15 minutes for propagation
- Tunnel URL is stable (ngrok with fixed domain)
- Server returns 202 for all callback paths
- Catch-all route handles /v3/, /api/v3/, /api/callbacks/v3/
- Discovery returns 202 then calls on-discover async
- REQUEST-ID from header used in response.requestId
- Middleware logs all incoming POSTs
- HTTPS certificate is valid
Still Stuck?
At Nirmitee, we have debugged dozens of ABDM callback issues. Reach out for help.



