Delivery and Retries

Webhook delivery on Kaiten Cloud is handled by Svix, a managed webhook provider: every subscribed event becomes a signed POST to your endpoint, failures are retried on a backoff schedule, and every attempt is recorded. Delivery is at least once — the guarantee is that a subscribed event reaches you, not that it reaches you exactly once.

Delivery lifecycle

1. Sending — the event is dispatched to your endpoint.
2. Success — your endpoint answers with a 2xx status; the delivery is complete.
3. Failure — a non-2xx status or a timeout; the next attempt is scheduled.
4. Failed — every retry attempt has been used; the delivery is closed as failed.

Retries

A failed attempt is retried automatically, on the provider's standard backoff, over more than a day. An endpoint that is down for a deploy or a short incident recovers its deliveries without any action on your side. When the schedule is used up, the delivery is closed as failed, and its attempts stay visible in the history.

Timeout

Your endpoint must answer promptly. A response that does not arrive within the provider's timeout counts as a failure and is retried like one. Acknowledge first, process afterwards.

Delivery history

The console's Integrations → Webhooks → History tab lists the most recent delivery attempts: the date, the endpoint, the event and the status — OK, Pending, Sending or Fail. A failed attempt adds the HTTP status and the response your endpoint returned. The same view over the API, with the read:webhooks scope:

curl "$KAITEN_API/webhooks/history" \
  -H "Authorization: Bearer $KAITEN_TOKEN"

The response is { "history": [...] }: the 50 most recent attempts of each endpoint, in one response without pagination. Each entry carries date, hookId, hookUrl, eventType, a status — success, pending, sending or fail — and, once the endpoint has answered, responseStatusCode and responseStatusText. The history is a bounded window: on a busy endpoint an attempt leaves it as newer ones arrive, so keep your own record of what you processed.

✕

✕

Writing a handler that survives retries

• Return 2xx fast. Persist the delivery and answer; do the work asynchronously. A handler that calls other systems before answering is the usual cause of timeouts.
• Deduplicate on svix-id. At least once means the same event can arrive twice — after a timeout on your side, for instance. The svix-id header is stable across attempts of the same delivery; store the ids you have processed and skip repeats.
• Verify before trusting. Check the signature on every delivery — verifying signatures. Reject with a 4xx if it does not verify; a 4xx is retried like any failure, so a misconfigured secret shows up in the history rather than silently dropping events.
• Watch the history. A failing endpoint is retried for more than a day before its deliveries are closed as failed; the History tab is where that shows first.

Where to go next

What an endpoint receives: payload examples. What it can subscribe to: the event catalog. Managing the endpoints themselves: managing endpoints.