Callbacks

The Callbacks API receives webhook payloads from AI providers and resolves the associated task automatically. No API key authentication is required - the callback ID acts as a one-time secret token.

Resolve a callback

POST /v1/callbacks/:callbackId

Path parameters

Parameter	Type	Required	Description
callbackId	string	Yes	The callback ID returned when the task was created. A 64-character hex token.

Request body

Any valid JSON payload. The entire body is stored as the task result. This is designed to accept the native webhook format from AI providers without transformation.

Example request

# Typically called by the AI provider, not your application
curl -X POST https://api.asyncqueue.io/v1/callbacks/a1b2c3d4e5f6... \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "abc-123",
    "status": "OK",
    "payload": {
      "images": [{"url": "https://example.com/result.png"}]
    }
  }'

Example response (200 OK)

{
  "task": {
    "id": "019d2b00-1234-7000-a000-000000000001",
    "status": "completed",
    "result": {
      "statusCode": 200,
      "headers": {},
      "body": "{\"request_id\":\"abc-123\",\"status\":\"OK\",\"payload\":{\"images\":[{\"url\":\"https://example.com/result.png\"}]}}",
      "duration": 0
    },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": "2025-01-15T10:30:45.000Z"
  }
}

---

Error responses

// 404 - Invalid or expired callback ID
{"error": "Invalid or expired callback ID"}

// 409 - Task is not in a resolvable state
{"error": "Task is not in waiting/polling state (current: completed)"}

// 429 - Rate limit exceeded
{"error": "Rate limit exceeded"}

Rate limiting

The callback endpoint is rate-limited by IP address at 30 requests per 60 seconds. This applies per source IP, not per callback ID.

Security

• Callback IDs are 64-character random hex tokens
• Each callback ID is single-use and invalidated after a successful resolution
• No API key or bearer token is required - the callback ID itself authenticates the request
• Expired or already-used callback IDs return a 404 error