API reference

Webhook deliveries API

Inspect and replay your webhook deliveries.

A delivery is one attempt-tracked row per (event × endpoint) pair — the durable state machine the platform drives to push an event to one of your webhook endpoints. This API lets you list your recent deliveries, read a single delivery's current state, and manually re-queue one for another attempt. Every operation is bearer-authenticated, scope-gated, and strictly scoped to deliveries you own.

Authentication and scopes

All three endpoints are part of the public /api/v1 surface. Authenticate with a developer API key as a bearer token — never cookies or CSRF. See Authentication for how to mint and send a key.

Authorization: Bearer krallo_live_<your-key>

A key holding the staff-only * wildcard satisfies either check. A key missing the required scope gets 403 insufficient_scope with the needed scope echoed in error.required_scope. See Scopes for the full vocabulary.

The delivery object

Every endpoint returns the same masked delivery shape. Only the fields below are exposed — internal columns such as the sending lease are never serialized.

Delivery status lifecycle

A delivery moves through these states as the delivery worker sweeps it:

Failed attempts are retried with capped exponential backoff up to a maximum attempt count (default 12), each rescheduling next_attempt_at further out (base 5s, capped at 10 minutes). After the budget is spent the delivery is marked dead. Repeated endpoint failures can also auto-disable the endpoint. Delivery is at-least-once: dedupe on event_id in your consumer.

List deliveries

Returns your recent deliveries across all of your endpoints, newest first (ordered by created_at descending, then id descending). Requires webhooks:read.

Query parameters

Request

curl https://exe.krallo.com/api/v1/webhooks/deliveries?limit=2 \
  -H "Authorization: Bearer krallo_live_<your-key>"

Response

200 OK — data is an array of delivery objects (possibly empty).

{
  "data": [
    {
      "id": "01J8ZC4R7M0F3A9Q2W5X8Y1B6D",
      "endpoint_id": "01J8ZC1A2B3C4D5E6F7G8H9J0K",
      "event_id": "01J8Z9K3M4P5Q6R7S8T9V0W1X2",
      "event_type": "imagine.completed",
      "status": "delivered",
      "attempt_count": 1,
      "next_attempt_at": null,
      "last_response_code": 200,
      "last_error": null,
      "created_at": 1752566400123,
      "updated_at": 1752566401987
    },
    {
      "id": "01J8ZB0H7K2M4N6P8R0T2V4X6Z",
      "endpoint_id": "01J8ZC1A2B3C4D5E6F7G8H9J0K",
      "event_type": "imagine.completed",
      "event_id": "01J8Z8Q1W2E3R4T5Y6U7I8O9P0",
      "status": "dead",
      "attempt_count": 12,
      "next_attempt_at": null,
      "last_response_code": 500,
      "last_error": "endpoint returned 500",
      "created_at": 1752560000000,
      "updated_at": 1752561800000
    }
  ],
  "meta": { "request_id": "e8c0a2d4-5f7b-4e9d-a1c3-6b8d0f2a4c6e" }
}

Retrieve a delivery

Returns the current state of a single delivery you own. Requires webhooks:read.

Path parameters

Request

curl https://exe.krallo.com/api/v1/webhooks/deliveries/01J8ZC4R7M0F3A9Q2W5X8Y1B6D \
  -H "Authorization: Bearer krallo_live_<your-key>"

Response

200 OK — data is the delivery object.

{
  "data": {
    "id": "01J8ZC4R7M0F3A9Q2W5X8Y1B6D",
    "endpoint_id": "01J8ZC1A2B3C4D5E6F7G8H9J0K",
    "event_id": "01J8Z9K3M4P5Q6R7S8T9V0W1X2",
    "event_type": "imagine.completed",
    "status": "delivered",
    "attempt_count": 1,
    "next_attempt_at": null,
    "last_response_code": 200,
    "last_error": null,
    "created_at": 1752566400123,
    "updated_at": 1752566401987
  },
  "meta": { "request_id": "f1d3b5a7-9c8e-4f0a-b2d4-7c9e1a3b5d7f" }
}

A delivery that does not exist — or that belongs to another developer — returns 404 not_found. See Ownership and access.

Replay a delivery

Re-queues a delivery for another attempt using the original event payload. Requires webhooks:write. The request body is ignored.

Replaying resets the delivery in place:

• status → pending
• attempt_count → 0
• next_attempt_at → now (it will be swept on the next worker pass)
• last_response_code and last_error → null

A replay does not create a new delivery id or event id — the same row is redriven, so your consumer receives the same event_id again. Attempt-log rows from the original round are preserved; the replay appends a fresh round.

Path parameters

Request

curl -X POST \
  https://exe.krallo.com/api/v1/webhooks/deliveries/01J8ZB0H7K2M4N6P8R0T2V4X6Z/replay \
  -H "Authorization: Bearer krallo_live_<your-key>"

Response

202 Accepted — the delivery has been re-queued; data is the delivery in its reset state.

{
  "data": {
    "id": "01J8ZB0H7K2M4N6P8R0T2V4X6Z",
    "endpoint_id": "01J8ZC1A2B3C4D5E6F7G8H9J0K",
    "event_id": "01J8Z8Q1W2E3R4T5Y6U7I8O9P0",
    "event_type": "imagine.completed",
    "status": "pending",
    "attempt_count": 0,
    "next_attempt_at": 1752570000000,
    "last_response_code": null,
    "last_error": null,
    "created_at": 1752560000000,
    "updated_at": 1752570000000
  },
  "meta": { "request_id": "a6c8e0d2-4b5f-4a7c-9e1b-3d5f7a9c1e3b" }
}

Ownership and access

Every operation is IDOR-scoped: the service joins each delivery through its endpoint and app to the owning account and filters on your identity (including your linked identities). A delivery id that does not resolve to one of your apps is indistinguishable from one that does not exist — both return 404 not_found. There is no way to read or replay another developer's delivery, and the 404 leaks nothing about whether the id is real.

Errors

Errors use the standard /api/v1 envelope: { "error": { "code", "message", … }, "meta": { "request_id" } }. See Errors for the full model.

Next steps

• Webhooks overview — endpoints, subscriptions, and delivery semantics.
• Event catalog — the events that produce deliveries, and their payloads.
• Signature verification — verify a delivery is genuinely from Krallo.
• Errors and Rate limits — the response envelope and limit headers.