Webhook 500 error: what it means and how to fix it

A 500 on a webhook means your endpoint threw while handling the delivery — not that the provider misbehaved. The provider sent a valid request, your handler errored, and the delivery is marked failed (and usually retried for a while, then dropped).

Common causes

• An unhandled exception in the handler — a nil/undefined field, a failed JSON parse, a bad type assumption.
• A downstream call failing (database, queue, another API) without a try/catch around it.
• Doing heavy work inline so the request errors or times out.
• Returning 500 on purpose for a case you should handle and 2xx instead (e.g. a duplicate event).

Confirm it in HookWatch

Open the failed delivery and read the response body your endpoint returned — it is usually the exact error message or stack line. Check the attempt history to see whether the provider already retried, and the request body so you can reproduce it locally. See webhook debugging for the full flow, or the step-by-step fixing webhook 500 errors guide.

Recover the delivery

Fix the handler, deploy, then replay the captured delivery so the event is processed — no need to ask the provider to resend.