HTTP status codes for webhooks

The short table

Code	Meaning for the sender	Use when
200 OK	Received and processed. Done.	The default answer
202 Accepted	Received, processing later.	You queued the job – the honest answer for async handling
204 No Content	Received, nothing to say.	Same as 200, without a body
400 Bad Request	Broken payload – usually no retry.	The body is genuinely unparseable
401 / 403	Not authorised – usually no retry.	Signature verification failed
404	Endpoint doesn't exist. Often disables the webhook.	Never on purpose
410 Gone	Endpoint permanently gone. Stop sending.	You deliberately shut it down
429	Too many requests – retry later.	You're rate limiting
500 / 503	Temporary failure – please retry.	Your database is down, a dependency failed

The rule of thumb

2xx = don't send again. 4xx = don't send again, it was our fault. 5xx = send again later. That's the whole logic. Everything else is nuance.

The mistakes that hurt

• Returning 500 on a bad payload. The provider retries a request that can never succeed – for hours or days.
• Returning 200 when processing failed. The event is gone forever; the provider considers it delivered. If you can't process it, say 500 and let the retry work for you.
• Answering slowly. Most providers time out after 5–30 seconds and count it as a failure – even if your code completed.
• Returning 4xx for a full quota. Careful: the sender may disable the endpoint after enough failures. If the request itself was fine, a 2xx with an explanation in the body is friendlier – that's exactly what Webhooky does when a free-plan limit is reached.

202 is underrated

If you queue work and answer immediately, 202 Accepted is more accurate than 200 OK: “I have it, I'll deal with it.” Providers treat both as success, and your logs stay truthful about what actually happened.

More: retries and idempotency · best practices

Get Webhooky

Free for your first 100 notifications – set up your endpoint in two minutes.