Docs | Kash

How each attempt is judged

Your endpoint’s answer	Result
`2xx`	Delivered. No more attempts.
`3xx`	Stopped. Redirects are not followed; register the final URL.
`400`, `404`, `410`, `422`	Stopped. The API reads these as “don’t send me this event”.
Any other `4xx` (including `408` and `429`)	Retried.
`5xx`	Retried.
No answer within 10 seconds	Retried.
Network or TLS error	Retried.

A stopped event has status: "failed" and a terminalFailureAt time in GET /v1/webhooks/events.

Automatic retries

A retryable failure is attempted again about 2 minutes later, up to 10 attempts in total, so automatic delivery gives up roughly 20 minutes after the first attempt. Treat the timing as approximate. Events for one API key are delivered in order, so a failing event holds back later events for the same key until it is delivered or its attempts run out. Fix a failing endpoint quickly, and replay anything that ran out of attempts. If your endpoint fails 5 times in a row, delivery to it pauses for about 60 seconds before a single trial attempt. Other customers’ deliveries are not affected.

Inspecting delivery state

curl 'https://api.kash.bot/v1/webhooks/events?status=failed,retrying&limit=20' \
  -H "X-API-Key: $KASH_API_KEY"

{
  "data": [
    {
      "id": "6f1c2a3b-9d0e-4f7a-8c1b-6e5d3f4a2c9b",
      "eventType": "trade.completed",
      "tradeRequestId": "11111111-1111-4111-8111-111111111111",
      "emittedAt": "2026-10-20T12:00:00.000Z",
      "outboxEmittedAt": "2026-10-20T12:00:00.400Z",
      "replayCount": 0,
      "status": "failed",
      "delivery": {
        "attempts": 1,
        "lastAttemptedAt": "2026-10-20T12:00:01.000Z",
        "lastDeliveredAt": null,
        "lastStatusCode": 404,
        "lastFailureCode": "terminal_client_error",
        "lastErrorMessage": "Customer endpoint returned 404",
        "terminalFailureAt": "2026-10-20T12:00:01.000Z"
      }
    }
  ],
  "pagination": { "cursor": null, "hasMore": false, "limit": 20 },
  "_meta": { "requestId": "…", "timestamp": "…" }
}

status filters: none, pending, retrying, delivered, failed, comma-separated. See Webhook management.

Manual redelivery

After fixing your endpoint, replay an event:

curl -X POST https://api.kash.bot/v1/webhooks/events/6f1c2a3b-9d0e-4f7a-8c1b-6e5d3f4a2c9b/redeliver \
  -H "X-API-Key: $KASH_API_KEY"

The answer is 202 Accepted with the event. The replay:

carries the same event id and X-Kash-Event-Id, so a receiver that already processed the event treats it as a duplicate;
is signed with the key’s current secret;
works on an event in any state, including one already delivered, which is handy for testing a handler with a real payload;
is itself retried like any delivery.

Each event can be replayed at most 5 times (429 WEBHOOK_REPLAY_LIMIT_REACHED after that). There is no bulk replay: list the failed events and replay them one by one.

Testing locally

The kash CLI can sign a payload the same way the API does and POST it to your endpoint, without touching production data:

kash webhooks replay payload.json \
  --target http://localhost:3000/webhooks/kash \
  --secret "$KASH_WEBHOOK_SECRET"

Use --timestamp-ms to test your freshness check, and kash webhooks verify to check a signature offline. To trace the trade behind an event, pass its correlationId to kash trace or GET /v1/traces/{correlationId}.

Common patterns

“My handler was broken for an hour”

Fix and redeploy the handler.
List GET /v1/webhooks/events?status=failed,retrying and walk the cursor.
POST …/redeliver each event id. Your deduplication makes this safe for events you did process.

Verifying signatures

Always verify before processing.

Secret rotation

Rotate without dropping deliveries.

Overview

REST API

Webhooks

REST API SDK (TypeScript)

CLI

Protocol SDK (TypeScript)

Protocol SDK (Python)

API Error Catalogue

Public Embed API

Embed — Thread Endpoints

Embed — Market Endpoints

Embed — Twitter Deep Links

Embed — Guides

Embed — Code Examples

Retries & Redelivery

How each attempt is judged

Automatic retries

Inspecting delivery state

Manual redelivery

Testing locally

Common patterns

“My handler was broken for an hour”

Next

Verifying signatures

Secret rotation

​How each attempt is judged

​Automatic retries

​Inspecting delivery state

​Manual redelivery

​Testing locally

​Common patterns

​“My handler was broken for an hour”

​Next

Verifying signatures

Secret rotation

How each attempt is judged

Automatic retries

Inspecting delivery state

Manual redelivery

Testing locally

Common patterns

“My handler was broken for an hour”

Next