Idempotency

Networks lose answers. A request you retry may already have been accepted, and an event we retry may already have reached you. Both directions have a way to make a repeat harmless.

Requests you send to flow triggersCopy Anchor Link

Send an Idempotency-Key header with every request to a flow trigger URL. Use an id your system already has for the event, such as order-10482-shipped, and send the same key on every retry of that event.

• A request whose key already started a run of the same flow starts nothing new. It is answered 200 with "status": "duplicate" and the id of the run the first request started, whether that run is still going or has ended.
• Keys are scoped to the flow: the same key sent to another flow's URL starts that flow. Replacing a flow's URL keeps its keys.
• A key is remembered for as long as the run it started exists. Ended runs are deleted 90 days after they end, and the key goes with them.
• Only a request that started a run is remembered. Any other answer (invalid_phone, flow_off, rate_limited, service_unavailable…) leaves nothing behind, so retrying with the same key after fixing the cause works.
• The body is not compared. A second request with the same key and a different body is answered duplicate and its body is ignored.
• Keys are at most 200 characters (400 idempotency_key_too_long otherwise), compared exactly and case-sensitively after leading and trailing spaces are removed. An empty header is the same as none.

Without a key, every accepted request starts a run, including a retry of one that was already accepted.

Events we send youCopy Anchor Link

Webhook delivery is at-least-once: the same event can reach you more than once, after a retry or a resend. Every delivery of one event carries the same envelope id (evt_…). Record the ids you have handled and acknowledge a repeat with 2xx without acting on it again.

Keep ids for at least as long as we might send the event again: retries run for about two days, and any delivery in the 30-day delivery log can be resent by hand. See Retries and the delivery log.