## 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

```text
provider dashboard shows endpoint disabled: 'delivery timed out after 3000ms'
```

## Steps

1. Return 200 immediately on receipt, before doing any work Expected: the provider sees a fast 2xx.
2. Push the event payload onto a queue or job table Expected: no event is lost.
3. Process the queue in a background worker Expected: slow work no longer blocks the webhook.
4. 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