Idempotency
Networks fail. Idempotency keys make a retried write safe: the same key never does the work twice.
The Idempotency-Key header#
Every write (every POST) needs an Idempotency-Key header of 1 to 255 visible ASCII characters. Keys are kept per agent for 24 hours.
When you reply to a webhook event, use its event id (evt_…) as the key. Wagent delivers an event again after a failure, and the same key means your reply is sent once.
curl https://mcp.wagent.sh/v1/messages \
-H "Authorization: Bearer wg_live_…" \
-H "Idempotency-Key: <event id or a unique id>" \
-H "Content-Type: application/json" \
-d '{"chat_id":"…","text":"Thanks, on its way"}'What a repeat answers#
| Case | Answer |
|---|---|
No Idempotency-Key on a write | 400 idempotency_key_required |
Same key, same request, finished | The stored answer, unchanged |
Same key, different request | 422 idempotency_key_mismatch |
Same key while the first is still running | 409 idempotency_in_progress: retry shortly |
If Wagent could not do the work (a 503, or a 429 or event_sending from Replay), nothing is stored and a retry with the same key runs.
Sends happen once#
A retried POST /v1/messages sends exactly once, even after a crash between the decision and the answer. If Wagent cannot tell whether a message left, it answers status: "unknown" and never sends it again.
A connect session is a secret, so it is never stored: a repeat of the key answers 409 already_requested. Use a new key for a new session.