webhook receiver timed out so agent marked every send as failed
Shows how to treat webhook timeouts as unknown instead of failed, and verify before resending. Use it when slow receivers cause false failure marks and duplicate retries. Not for building the receiver itself or for payload validation.
TL;DR
A timeout means unknown, not failed. Mark the send as pending, then check the receiver's status endpoint (or your own outbox log) before deciding to retry. Marking timeouts as failed and retrying blindly creates duplicate deliveries on the other end. Three states, not two: sent, pending, failed.
webhook receiver timed out so agent marked every send as failedUse this when
- slow webhooks get marked failed and resent
- the receiver processed the payload but the agent retried anyway
- your send log has only success and failure with no pending state
Not for this skill when
- the receiver rejects the payload (fix the payload)
- you are writing the webhook receiver from scratch
- authentication to the receiver is broken
Steps
- Add a pending status to your send log between attempted and confirmed. Verify: a send has three possible states, not two.
- On timeout, leave the status at pending and record the attempt time. Verify: the row is not marked failed.
- Before any retry, query the receiver for the event by your idempotency key or check your outbox. Verify: the check runs before every retry attempt.
- Retry only if the receiver has no record of the event, reusing the same idempotency key. Verify: the retry payload is byte-identical to the first.
- After 3 unconfirmed attempts, escalate to a human instead of retrying forever. Verify: the send stops and an alert fires.
Tool/version compatibility
Any webhook sender in any language. Works with idempotency-key style APIs or your own UUID per event.
Why it happens
The agent maps every non-200 outcome to failed, but a timeout is the one outcome where the receiver may have succeeded. The two-state model cannot represent reality.
Edge cases / pitfalls
- Some receivers process slowly but acknowledge fast; a timeout usually means network trouble, not receiver trouble.
- Duplicate deliveries are the receiver's problem too: include the idempotency key in the payload so they can dedupe.
- Never treat a connection timeout as permission to fire all retries at once; space them with backoff.
Variant phrasings
Webhook timeouts caused duplicate deliveries
Short version: timeout marked as failed, retried blind.
Agent kept resending webhooks the receiver already got
Short version: no pending state, no verification.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_YIAlSnwxspVFLWlTfE6HQQ