Callback URLs

Some AI providers support sending a webhook when a job finishes instead of requiring you to poll for status. AsyncQueue generates a unique callback URL for each task so providers can notify us directly when results are ready.

How It Works

1. Include {asyncqueue_callback_url} anywhere in your task body
2. AsyncQueue generates a unique callback URL and substitutes it before making the HTTP call
3. The AI provider receives the callback URL as its webhook destination
4. When the provider POSTs results to the callback URL, the task completes automatically
5. Your onCompleteUrl webhook receives the final output

Your App             AsyncQueue              AI Provider
  |                      |                      |
  |-- POST /v1/tasks --->|                      |
  |   body includes      |                      |
  |   {asyncqueue_       |                      |
  |    callback_url}     |                      |
  |<-- 201 + callbackUrl |                      |
  |                      |-- POST to provider ->|
  |                      |   (callback URL      |
  |                      |    substituted)       |
  |                      |                      |
  |   ... time passes ...                       |
  |                      |                      |
  |                      |<-- POST callback ----|
  |                      |   (provider sends    |
  |                      |    results)           |
  |                      |                      |
  |<-- onCompleteUrl ----|                      |
  |   webhook with result|                      |

Example: fal.ai with Webhook

fal.ai supports a fal_webhook query parameter. Use {asyncqueue_callback_url} as the value:

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "X-API-Key: async_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://queue.fal.run/fal-ai/flux/dev?fal_webhook={asyncqueue_callback_url}",
    "method": "POST",
    "headers": {
      "Authorization": "Key fal_your_key"
    },
    "body": "{\"prompt\": \"A sunset over mountains\"}",
    "waitForSignal": true,
    "maxWaitTime": 600,
    "onCompleteUrl": "https://your-app.com/api/image-ready"
  }'

Response:

{
  "task": {
    "id": "019d2b00-1234-7000-a000-000000000001",
    "status": "pending",
    "callbackId": "a1b2c3d4..."
  },
  "callbackUrl": "https://api.asyncqueue.io/v1/callbacks/a1b2c3d4..."
}

When fal.ai finishes processing, it POSTs the result to the callback URL. AsyncQueue receives the payload and completes the task automatically.

Example: Replicate with Webhook

Replicate supports a webhook field in the prediction request body:

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "X-API-Key: async_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.replicate.com/v1/models/stability-ai/stable-diffusion-3/predictions",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer r8_your_token"
    },
    "body": "{\"input\": {\"prompt\": \"An astronaut\"}, \"webhook\": \"{asyncqueue_callback_url}\", \"webhook_events_filter\": [\"completed\"]}",
    "waitForSignal": true,
    "maxWaitTime": 600,
    "onCompleteUrl": "https://your-app.com/api/prediction-ready"
  }'

How the Callback Endpoint Works

The callback endpoint accepts any JSON payload from the AI provider:

POST /v1/callbacks/:callbackId

• No API key authentication required (the callbackId itself is a secret token)
• Accepts any JSON body - the full provider payload is stored as the task result
• Rate-limited by IP address (30 requests per minute)
• One-time use - the callback ID is invalidated after the first successful call

See the Callbacks API Reference for full endpoint details.

Callback URL vs Polling

Feature	Callback URL	Polling
Provider support	Only providers with webhook support	Any provider with a status endpoint
Latency	Instant notification	Depends on poll interval
Setup	Include {asyncqueue_callback_url} in body	Set provider or pollConfig
Best for	fal.ai, Replicate, Luma AI	RunwayML, Stability AI, ElevenLabs

For providers that support both, callback URLs deliver results faster. For providers without webhook support (like RunwayML or Stability AI), use AI Provider Polling instead.

Security

• Callback IDs are 64-character random hex tokens (256-bit entropy)
• Each callback ID is single-use and invalidated after resolution
• The callback endpoint is rate-limited by IP address
• No authentication headers are required - the callback ID acts as the secret