Idempotency

Payments get retried. Networks drop, timeouts fire, workers restart. Sentinel makes retries safe with an idempotency key on every event.

How it works

• idempotency_key is required on every POST /v1/events.
• It's unique within your organisation.
• The first request with a given key stores the event and, in sync mode, scores it.
• Any later request with the same key returns the original event and decision. Nothing is stored or scored twice.

Choosing a key

Use the ID your own system already gives the transaction, such as your payment or ledger transaction ID. It must be:

• Stable. The same transaction always gets the same key, including on retries from a different process.
• Unique. Two different transactions never share a key.

{
  "type": "transfer.outbound",
  "idempotency_key": "txn_8f2a91",
  "occurred_at": "2026-10-15T11:02:41Z"
}

Retrying

Retry on network errors, timeouts and 5xx responses, with backoff, using the same key. Don't retry 400 or 401; the request won't succeed until you fix it.

A replay in sync mode returns the stored decision, including its alert_id if one was raised. If an earlier attempt stored the decision but failed before putting it on an alert, the replay does that, so every review or block decision ends up on exactly one alert.

An event first sent in async mode and replayed with mode=sync is scored on the replay, because async mode only stores it.