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?
| Endpoint | Response | Use it to test |
|---|---|---|
/status/500 | 500 Internal Server Error | a crashed handler |
/status/503 | 503 Service Unavailable | an endpoint that is down |
/status/429 | 429 Too Many Requests | rate limiting |
/status/400 | 400 Bad Request | a rejected payload |
/status/200,500 | 200 or 500 at random | a flaky endpoint |
/delay/10 | 200 after 10 seconds | timeouts (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.