Fix a Broken Webhook Integration: A Debugging Guide

A webhook integration that "just stopped working" usually hasn't actually stopped — either the sender changed something, your endpoint changed something, or the two sides have quietly drifted out of sync. Finding out which requires looking at both ends, not just assuming your code is the problem.

First: Is It Even Arriving?

Before touching your own code, check whether the webhook is being sent at all. Most platforms with webhooks — Stripe, Shopify, GoHighLevel, GitHub — keep a delivery log showing every attempt, the response code your endpoint returned, and whether it was marked successful. This single check usually narrows the problem to "sender side" or "receiver side" immediately.

The Most Common Real Causes

1. Your Endpoint Is Timing Out

Most webhook senders expect a fast response (often under 5-10 seconds) and will mark the delivery as failed — or retry it, sometimes duplicating actions — if your endpoint takes too long. If your endpoint does heavy processing before responding, move that processing to run asynchronously after you've already returned a 200.

2. The Payload Structure Changed

APIs evolve. A field that used to always be present might become optional, get renamed, or move to a nested object. If your parsing code expects the old structure, it can fail silently or throw an error deep in your logic rather than at the point of receiving the webhook.

3. Authentication or Signature Verification Is Failing

If your endpoint verifies a webhook signature or shared secret, a rotated API key, an expired token, or a small implementation difference in how the signature is computed can cause every webhook to be silently rejected — often with no obvious error unless you specifically log verification failures.

4. Retries Are Creating Duplicate Actions

If a sender retries a webhook it thinks failed (even if your endpoint actually processed it), and your logic isn't idempotent, you can end up with duplicate records or repeated actions — which looks like "broken" behavior but is actually a retry-handling gap.

5. IP Allowlisting or Firewall Changes

If your server or the sending service changed IP ranges, and either side has IP-based restrictions, webhooks can be silently blocked at the network level before your application code ever sees them.

How to Debug This Properly

Check the sender's delivery logs first — this alone often tells you whether the problem is upstream or in your own system. If it's arriving, log the complete raw payload before any parsing so you can compare what's actually being sent against what your code expects. Only after confirming both delivery and payload shape should you look at your own processing logic for the actual bug.

Frequently Asked Questions