How to test webhook retries and failure responses

The quick answer: point the sender at an endpoint that returns an error, such as https://webhook.plus/status/500, and watch its delivery log. Most senders treat any non-2xx response or a timeout as a failed delivery and retry later with a backoff.

Which endpoints return errors?

EndpointResponseUse it to test
/status/500500 Internal Server Errora crashed handler
/status/503503 Service Unavailablean endpoint that is down
/status/429429 Too Many Requestsrate limiting
/status/400400 Bad Requesta rejected payload
/status/200,500200 or 500 at randoma flaky endpoint
/delay/10200 after 10 secondstimeouts (see slow endpoints)
curl -i -X POST https://webhook.plus/status/503 -d '{}'
HTTP/2 503

How do I return a custom error body and headers?

/reply lets you choose everything. Pass headers as a JSON object:

curl -i 'https://webhook.plus/reply?status=429&body=slow%20down&headers=%7B%22Retry-After%22%3A%2230%22%7D'

That returns 429 with Retry-After: 30 and the body slow down. Some senders honour Retry-After; many don't. Testing tells you which.

POST works too, which is easier to read:

curl -i https://webhook.plus/reply -H 'content-type: application/json' \
  -d '{"status":503,"body":"maintenance","headers":{"Retry-After":"120"}}'

What should I look for in the sender's log?

  • Which statuses count as failures. Usually anything outside 2xx. Some senders treat 3xx redirects as failures rather than following them.
  • Retry schedule. How many attempts, and how far apart.
  • Whether retries repeat the same event ID. If they do, your handler must be idempotent.
  • When the sender gives up. Some disable an endpoint after repeated failures.

Make your real handler retry-safe

Retries mean duplicates. Store the event or delivery ID and skip events you've already processed. Return 2xx quickly and do slow work in the background, so a slow handler doesn't trigger retries of its own.

All test traffic is recorded; use sandbox events.

Frequently asked questions

Will a 4xx response stop retries?

It depends on the sender. Many retry any non-2xx response, while some stop on specific 4xx codes. Point the sender at /status/400 or /status/410 and check its delivery log.