ABDM Callback Debugging: Why Your Bridge URL Is Not Receiving Requests

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.

1. ABDM calls your discovery endpoint
2. Return 202 Accepted immediately
3. Call /on-discover with 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.