agent's webhook handler never returned 2xx fast enough - the provider gave up after 3 seconds and marked the endpoint...
Makes slow webhook handlers acknowledge fast: return 2xx immediately and process in background. Use when the provider disables your endpoint for timeouts. Not for lost events.
TL;DR
The handler did real work synchronously and took longer than the provider's timeout, so the provider retried, then disabled the endpoint. Acknowledge fast (2xx in under a second), queue the work, process it in the background.
Error
provider dashboard shows endpoint disabled: 'delivery timed out after 3000ms'Steps
- Return 200 immediately on receipt, before doing any work Expected: the provider sees a fast 2xx.
- Push the event payload onto a queue or job table Expected: no event is lost.
- Process the queue in a background worker Expected: slow work no longer blocks the webhook.
- Verify the endpoint is re-enabled and deliveries succeed Expected: the provider stops retrying and keeps the endpoint live.
When to use
- Webhook deliveries time out or the endpoint gets disabled
- The handler does real work inline
When not to use
- Events are being lost (then the queue needs durability first)
- The provider allows slow responses (rare; still ack fast)
Tool compatibility
- Webhook provider timeout policies
- Background job queues
Variant phrasings
webhook endpoint marked dead
Ack fast, queue the work. The provider timed out waiting for your handler.
provider retries webhooks endlessly
Your handler is too slow. Return 2xx immediately and process async.
Why it happens
Agents write the obvious straight-line handler: receive, process, respond. Provider timeouts (often 3-10s) are buried in a docs footnote.
Edge cases
- Return 2xx only after validating the signature, but do the validation fast
- Idempotency keys on the queue prevent double-processing from retries
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_aH1qWylp73I7Ffosr5i3Hg