Run slow AI jobs asynchronously with webhook callbacks
Return an instant HTTP 202 job ID for multi-page extraction or chained prompts, then POST completed JSON to your callback URL.
Checklist for async AI callback pipelines
- 01
Return immediate 202 acceptance
Validate input schema synchronously and return a job_id within milliseconds before queuing inference.
- 02
Attach caller correlation IDs
Accept a pass-through metadata or correlation_id object echoed back inside the completion callback.
- 03
Sign outbound callback requests
Verify APIkit callback signatures on your receiver endpoint before committing results to your database.
- 04
Handle terminal failure callbacks
Send structured error payloads to your callback or failure webhook if upstream steps exhaust retries.
How it works in practice
1. Client Triggers Async Endpoint
POST /v1/analyze-rfp?mode=async { "doc_url": "https://cdn.example.com/rfp-42.pdf", "callback_url": "https://app.example.com/hooks/apikit", "correlation_id": "rfp_9921" }
2. Instant 202 + Later Callback POST
Immediate: 202 Accepted {"job_id":"job_7f3a","status":"queued"} Callback (18s later): POST /hooks/apikit {"job_id":"job_7f3a","correlation_id":"rfp_9921","status":"succeeded","result":{"requirements_count":14}}
Vercel, Cloudflare, and mobile clients stay snappy under 100ms while heavy AI chains complete safely in the background.
Common questions
Why use async callbacks instead of holding HTTP connections open?
Browser requests, serverless edge functions, and mobile networks frequently time out after 10–30 seconds. Async jobs eliminate dropped connections.
Can clients poll status if we do not expose a webhook URL?
Yes. Every queued async execution supports status polling by job_id until completion or failure.
How long are completed async payloads retained?
Configurable retention windows store job results temporarily for polling retrieval while pushing the live callback immediately.
Related tasks in this category
See all in Webhook & Async Event Pipelines-
Enrich incoming webhooks with AI before forwarding
Receive webhook events from GitHub, Linear, or Shopify, enrich payloads with structured AI classification, and relay clean JSON downstream.
-
Sign and verify AI webhook callbacks with HMAC headers
Protect downstream endpoints from forged callbacks using timestamped HMAC-SHA256 signature headers and replay window checks.
-
Recover failed webhook deliveries with retries and DLQ
Never lose completed AI outputs when your receiver restarts—automatically retry with exponential backoff and inspect dead-letter queues.
-
Fan out batch arrays into parallel AI endpoint runs
Split one bulk webhook containing 50 items into concurrent per-item model executions, then aggregate typed results cleanly.
-
Deduplicate duplicate webhook runs with idempotency keys
Prevent double token billing and duplicate database updates when third-party senders retry slow or flaky webhook deliveries.
-
Turn raw app events into crisp Slack or Discord alerts
Convert noisy JSON error traces, signups, and churn signals into readable Slack Block Kit summaries delivered automatically.