UXDL Docs
AI

Webhooks & Reconciliation

Receive run completion and recover when callbacks are missed.

How the product API receives hosted LangGraph run completion and recovers when callbacks are missed.

Webhooks

LangGraph POSTs to the product API when a run reaches a terminal state.

Handler responsibilities:

  • Parse thread_id, run_id, status, and values.
  • Extract the assistant or job result from values (field names vary by graph; document them per graph).
  • Write durable rows to the product database.
  • Update job status, record usage limits, and emit realtime events if needed.
  • Store trace IDs (langfuse_trace_id, trace_id) when present for debugging.

Mount webhooks on stable paths (e.g. POST /webhooks/agent, POST /webhooks/jobs/:type). One handler can serve multiple run types if payload parsing is explicit.

For durable vs streamed output, see Streaming & realtime.

Stale-run reconciliation

Webhooks are often missed in local dev or after network blips. Any async AI job exposed via GET should reconcile stuck processing rows:

ts
const run = await client.runs.get(threadId, runId);
if (runIsTerminal(run.status)) {
  const state = await client.threads.getState(threadId);
  const output = state.values?.expected_output_key;
  // persist output and update status
}

Call reconciliation from the read path (e.g. GET /jobs/:id) when status is still processing or generating.

Local debugging: Local development.

See also

Official documentation