Webhook Response Codes Explained

A status code is a three-digit number your system sends back after it receives a webhook. It tells the sending app whether the message arrived and was accepted. Senders such as Stripe and GitHub look for a code in the 200s, written 2xx, as the sign of success¹².

The first digit gives the family³. Each family points to a different place to look.

200: it worked

The request succeeded³. Stripe's documentation says that when an event shows a status code of 200, it indicates successful delivery to the webhook endpoint¹.

GitHub asks for any 2XX code, and says your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery². Read your sender's own rule.

Speed matters. Stripe tells developers to defer complex logic and return a successful response immediately in webhook handling code¹. In plain terms: reply first, do the slow work afterward.

400: the request was rejected

A 400 is MDN's label for a request the server refuses to handle because it looks like the sender's mistake, such as broken syntax³. For a webhook, the "client" is the sending app.

Stripe's example handler code returns 400 when the payload can't be parsed or the signature check fails¹. If a sender's log shows 400, look at your own receiving code first.

Stripe groups all 4xx codes together. It says they can mean the server detected an error (400), that the URL has access restrictions (401, 403, 405), or that the URL doesn't exist (404)¹.

404: the address doesn't exist

A 404 says the server has nothing at the address it was sent to³. For a webhook, that points at the URL, which Stripe lists as a case where the destination doesn't exist¹.

Check these in order:

1. Compare the URL in the sending app to the one your system listens on, character by character.
2. Look for a missing or extra slash, a typo in the route, or an old address after a site move.
3. Confirm the receiving route accepts POST requests. Stripe's advice for 4xx codes is to make sure the endpoint is publicly accessible and accepts a POST HTTP method¹.

500: the receiver failed

A 500 is a catch-all error for a server that hit a problem it couldn't handle³. Stripe says the receiving server ran into an error while processing, and it points you to your application's logs¹.

The fault sits on the receiving side. The sender did its job, but your system broke while handling the message.

Other codes you may meet

A timeout isn't a code at all. Stripe lists it as its own case, for a receiver that answers too slowly¹.

What to send from your side

Return a 2xx code as soon as the message is received, then do the slow work. Stripe and GitHub both ask for a quick reply¹².

What happens after a failure depends on the sender. The sender's retry rules are in Webhook Retries and Failed Deliveries.