Skip to content

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.

Copy the prompt and paste it into the AI assistant you already use.

Checklist for async AI callback pipelines

  1. 01

    Return immediate 202 acceptance

    Validate input schema synchronously and return a job_id within milliseconds before queuing inference.

  2. 02

    Attach caller correlation IDs

    Accept a pass-through metadata or correlation_id object echoed back inside the completion callback.

  3. 03

    Sign outbound callback requests

    Verify APIkit callback signatures on your receiver endpoint before committing results to your database.

  4. 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.