Webhook Callbacks

AsyncQueue uses webhooks as the execution mechanism for tasks. When a task is ready to run, AsyncQueue sends an HTTP POST request to your specified endpoint with the task payload. If the call fails, it retries automatically based on your queue’s retry policy.

How webhooks work

1. You create a task with a webhook_url pointing to your application
2. When the task is ready (immediately, or after a configured delay), AsyncQueue calls your endpoint
3. Your endpoint processes the task and returns a response
4. A 2xx response marks the task as completed; any other status triggers a retry

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue": "notifications",
    "webhook_url": "https://your-app.com/webhooks/notify",
    "payload": {
      "user_id": "usr_123",
      "message": "Your export is ready"
    }
  }'

Your endpoint receives:

{
  "task_id": "task_abc123",
  "queue": "notifications",
  "payload": {
    "user_id": "usr_123",
    "message": "Your export is ready"
  },
  "attempt": 1
}

Built-in retries

When your endpoint returns a non-2xx status or times out, AsyncQueue automatically retries the request. You can configure retry behavior per queue:

Setting	Default	Description
max_retries	3	Number of retry attempts
retry_backoff	exponential	fixed or exponential backoff
timeout	30s	How long to wait for your endpoint to respond

With exponential backoff, retry delays increase progressively: 1s, 2s, 4s, 8s, and so on. This prevents overwhelming your service during outages.

Webhook security

AsyncQueue signs every webhook request so you can verify it came from us. Each request includes an X-AsyncQueue-Signature header containing an HMAC-SHA256 signature computed with your API key.

Flexible endpoints

• Use any publicly accessible HTTP endpoint
• Route different task types to different services
• Use a single endpoint with routing logic based on the payload
• Point to serverless functions, containers, or traditional servers