Callback API

Send a Webhook

The external service sends an event using POST, PUT, or PATCH on the callback host: https://cb.exende.dev/hooks/{callback_id}.

curl -X POST \
  https://cb.exende.dev/hooks/cb_3t2cC09baD4yOvoeVMDK2vGQ \
  -H "Content-Type: application/json" \
  -d '{"status":"completed","result":"https://example.com/output"}'

{
  "received": true,
  "event_id": "evt_6ec6e7b4a917d63861a07d9238d4cf6d"
}

JSON bodies are validated before storage. Binary and file uploads are not supported. Only content-type, user-agent, stripe-signature, svix-id, svix-timestamp, svix-signature, x-hub-signature, x-hub-signature-256, webhook-id, webhook-timestamp, webhook-signature, x-signature, and x-webhook-signature headers are retained.

Callback ID validation and per-callback rate limiting run before callback lookup and body parsing. POST, PUT, and PATCH use the same handler and return the same response and error shapes.

Wait for an Event

GET https://api.exende.dev/v1/callbacks/{id}/wait

Authentication: Authorization: Bearer ex_cb_sk_...

curl \
  "https://api.exende.dev/v1/callbacks/cb_3t2cC09baD4yOvoeVMDK2vGQ/wait?timeout=30" \
  -H "Authorization: Bearer ex_cb_sk_..."

{
  "received": true,
  "timeout": false,
  "event": {
    "id": "evt_6ec6e7b4a917d63861a07d9238d4cf6d",
    "received_at": "2026-08-22T14:05:17.000Z",
    "method": "POST",
    "content_type": "application/json",
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "status": "completed",
      "result": "https://example.com/output"
    },
    "size_bytes": 60
  },
  "next_wait_url": "/v1/callbacks/cb_3t2cC09baD4yOvoeVMDK2vGQ/wait?after=evt_6ec6e7b4a917d63861a07d9238d4cf6d&timeout=30"
}

{
  "received": false,
  "timeout": true,
  "after": null
}

When an event is received, the response includes received: true, timeout: false, the full event object, and a relative next_wait_url. A timeout returns received: false, timeout: true, and after as the supplied event ID or null. An unknown after event returns HTTP 404 EVENT_NOT_FOUND.

Read All Events

GET https://api.exende.dev/v1/callbacks/{id}/events

Authentication: Authorization: Bearer ex_cb_sk_...

curl \
  https://api.exende.dev/v1/callbacks/cb_3t2cC09baD4yOvoeVMDK2vGQ/events \
  -H "Authorization: Bearer ex_cb_sk_..."

{
  "callback_id": "cb_3t2cC09baD4yOvoeVMDK2vGQ",
  "status": "active",
  "expires_at": "2026-08-22T14:30:00.000Z",
  "event_count": 1,
  "events": [
    {
      "id": "evt_6ec6e7b4a917d63861a07d9238d4cf6d",
      "received_at": "2026-08-22T14:05:17.000Z",
      "method": "POST",
      "content_type": "application/json",
      "headers": {
        "content-type": "application/json"
      },
      "body": {
        "status": "completed",
        "result": "https://example.com/output"
      },
      "size_bytes": 60
    }
  ]
}

Returns callback_id, status, expires_at, event_count, and all stored events ordered by received_at ascending. Each event includes id, received_at, method, content_type, filtered headers, body, and size_bytes. JSON bodies are returned as parsed JSON; text and form bodies remain strings. Events with the same second-level received_at timestamp preserve deterministic receipt order. Events are read-only.

Delete Callback

DELETE https://api.exende.dev/v1/callbacks/{id}

Authentication: Authorization: Bearer ex_cb_sk_...

curl -X DELETE \
  https://api.exende.dev/v1/callbacks/cb_3t2cC09baD4yOvoeVMDK2vGQ \
  -H "Authorization: Bearer ex_cb_sk_..."

{
  "deleted": true,
  "callback_id": "cb_3t2cC09baD4yOvoeVMDK2vGQ"
}

Deletes the callback and its stored events before automatic expiration.

Expiration

Callbacks live for 10 minutes. Expired callbacks are automatically cleaned up.

Limits

Errors

These are the standard error codes used across the Callback API. Each endpoint section above lists the subset it can return.

Authenticated routes validate the callback ID first, then the Authorization header and Bearer scheme, callback existence, read token, and expiration in that order.

A missing Authorization header returns MISSING_AUTHORIZATION. A non-Bearer header returns INVALID_AUTHORIZATION. An empty or incorrect Bearer token returns INVALID_TOKEN.

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The read token is invalid.",
    "request_id": "req_81731247-7585-44a8-8716-d9dda3e0ff61"
  }
}

Error responses include request_id.

Typical AI Agent Workflow