Webhook 500 errors: what they mean and how to recover

A 500 on a webhook means your endpoint accepted the request and then threw while handling it. It is a server error on your side, not the provider’s — which is good news, because it is something you can fix. The trick is reading the failed response and recovering the deliveries the provider gave up on.

What a 500 actually means

The provider reached your endpoint, sent a valid request, and your handler responded with 500 Internal Server Error (or a related 502/503 from a proxy in front of it). To the provider the delivery failed, so it will retry a few times and then stop. Anything not recovered in that window is dropped unless you captured it.

Common backend causes

• Unhandled exception — a nil/undefined access, a failed type assertion, or an unguarded edge case in the payload.
• Database error — a constraint violation, a dead connection, or a lock timeout mid-transaction.
• Downstream dependency — an API or queue you call inside the handler is down or slow.
• Deploy window — the handler was mid-restart, or a bad release shipped and every delivery 500s until you roll back.
• Work done inline — heavy processing in the request path fails under load instead of being queued.

Provider retry behaviour

Most providers retry a failed delivery on a backoff schedule for a limited window (minutes to a day or two, depending on the provider) and then give up. Retries help with a transient blip, but they will not save you from a bug that fails every time — every retry returns 500 too, and then the event is gone.

How to inspect the failed response

• Response body — the error your handler returned usually names the exception or failed query.
• Request body — the exact payload that triggered it, so you can reproduce the failure locally.
• Attempts — whether the provider retried and whether any attempt succeeded, so you do not double-process.

The step-by-step order is in how to debug a failed webhook.

How to replay safely once fixed

After you have deployed the fix, re-send the captured deliveries the provider already dropped. Confirm your handler is idempotent first, replay one delivery, and verify the result before doing the rest — the full method is in replay a failed webhook safely. HookWatch keeps each failed delivery with its request and response, so the payload is still there to replay after the provider has given up.