API reference

Base URL: https://api.stafett.dev

All job endpoints require:

Authorization: Bearer stf_…

Prefer to click around? The interactive OpenAPI explorer has the full schema, request/response examples, and a built-in "Authorize" button, and the raw spec is at /openapi.json.

Enqueue

POST /enqueue

{
  "callback_url": "https://api.example.com/hooks/ship",
  "payload": {"order": 42},
  "headers": {"x-source": "checkout"},
  "delay_seconds": 0
}
Field Required Contract
callback_url yes HTTPS URL, at most 2,048 characters
payload no Any JSON value, at most 1 MiB when compactly encoded; defaults to null
headers no Up to 50 string headers; each value at most 4,096 characters
delay_seconds no Non-negative integer; defaults to 0

Returns 202 Accepted:

{
  "id": "018f3b7c-6c4a-7b32-9f21-2c0a5e4d9b11",
  "status": "queued",
  "status_url": "/jobs/018f3b7c-6c4a-7b32-9f21-2c0a5e4d9b11"
}

Job status

GET /jobs/{id}

Returns:

{
  "id": "018f3b7c-6c4a-7b32-9f21-2c0a5e4d9b11",
  "status": "delivered",
  "attempts": 1,
  "created_at": "2026-08-03T16:00:00Z"
}

Possible statuses:

  • queued: waiting for delivery
  • delivering: an attempt is in progress
  • retrying: a retryable attempt failed and is backing off
  • delivered: the callback returned a 2xx response
  • dead: the failure is terminal or the retry budget is exhausted

An unknown job ID returns 404.

Delivery and retries

Stafett POSTs the exact JSON payload bytes to callback_url.

  • 2xx marks the job delivered.
  • Connection failures, timeouts, 429, and 5xx responses retry with exponential backoff while attempts remain.
  • Other non-2xx responses move the job directly to dead.
  • A retryable failure on the final configured attempt also moves to dead.

Delivery is at-least-once. Callback handlers must be idempotent.

Callback signatures

Every attempt follows the Standard Webhooks signing contract:

webhook-id: 018f3b7c-6c4a-7b32-9f21-2c0a5e4d9b11
webhook-timestamp: 1785772800
webhook-signature: v1,...
content-type: application/json

webhook-id is the Stafett job ID and stays stable across retries. Use it as the idempotency key. webhook-timestamp and webhook-signature are generated for each attempt. Stafett's signing headers override any conflicting values in the enqueue request.

Verify the signature over the raw request body with a Standard Webhooks-compatible library. Do not parse and re-encode the JSON before verification.

Common errors

  • 401: bearer token missing, invalid, or revoked
  • 404: job not found for the authenticated account
  • 422: request validation failed