Webhook operations · Troubleshooting
How to debug webhook delivery failures
Follow one event from the provider to your application. This checklist helps separate connection problems, rejected signatures, handler bugs, and retry duplicates.
By the Hookflo engineering team · Updated October 10, 2026
A webhook failure is a chain, not a single error
A webhook travels from an event in a provider, through an HTTP request, into your endpoint, and then through your application’s handler. To find the break, use the same event ID and timestamp across each step. Avoid starting with a code change until you know whether the request was sent, received, authenticated, and processed.
1. Find the exact delivery attempt
Start in the sender’s delivery history. Record the event ID, timestamp, destination URL, attempt number, response status, and response body. Confirm that the sender actually attempted the event and that you are looking at the right environment, account, and endpoint.
2. Check reachability before application code
Make sure the endpoint is public over HTTPS, its certificate is valid, and the route accepts POST requests. Check DNS, firewall rules, proxy limits, and whether a deploy or secret rotation changed the endpoint. A request that never reaches your server cannot be fixed in the event handler.
3. Read the response status and timing together
A 2xx response usually tells the sender that the request was accepted; a timeout or non-2xx response may trigger another attempt. Compare the sender’s timeout policy with your server logs. GitHub, for example, expects a 2xx response within 10 seconds and terminates slower connections.
4. Verify the signature against the original bytes
If your endpoint returns an authentication error, check the provider-specific signature header and the secret for that exact endpoint and environment. Signature checks commonly fail when JSON middleware parses the body before verification, when test and live secrets are mixed, or when a secret was rotated in only one system. Follow the sender’s official verification instructions; header names and signing formats differ.
5. Confirm event subscriptions and handler assumptions
A valid request can still be ignored by your app. Check that the sender is subscribed to the event type you expect, then inspect the event type and action fields before accessing nested data. Providers add event types and optional fields over time, so handlers should tolerate fields they do not use.
6. Make retries safe with idempotency
A sender may retry after a timeout even if your application completed the work but its response was lost. Store the provider’s stable delivery or event ID with a uniqueness constraint, and make the business operation safe to repeat. A duplicate should be acknowledged without creating a second payment, email, or record.
7. Redeliver only after the cause is fixed
Once the endpoint is healthy, retry or redeliver the original event from the provider’s dashboard or API. Do not assume every sender retries automatically: GitHub documents manual or scripted redelivery for failed webhook deliveries. Keep the original event ID in your logs so the replay can be traced end to end.
Keep the delivery trail in one place
When an event crosses providers, application logs, and alert channels, the hard part is often finding the matching attempt. Hookflo records supported incoming webhook deliveries, verifies configured signatures, and gives teams a searchable delivery history with Slack and email alerts.