{"id":1128,"date":"2026-05-19T17:00:00","date_gmt":"2026-05-19T22:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1128"},"modified":"2026-03-07T03:34:55","modified_gmt":"2026-03-07T08:34:55","slug":"webhook-debugging","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/webhook-debugging\/","title":{"rendered":"Debugging Webhooks: Tools and Techniques"},"content":{"rendered":"\n

Webhooks are straightforward in concept: an event happens, an HTTP POST gets sent to your server. In practice, they are one of the most frustrating things to debug. The request originates from someone else's infrastructure, there is no browser DevTools to inspect, and when something goes wrong the only evidence is a cryptic error in a log (or no log at all).<\/p>\n\n\n\n

If you have already set up a webhook endpoint (see the webhook setup guide<\/a> if you have not), this article covers what to do when things break. We will walk through the most common failure modes, tools for local development, logging strategies that actually help, and monitoring approaches that catch problems before your users notice.<\/p>\n\n\n\n

For a broader look at how webhooks fit into deep linking workflows, see the webhooks and integrations overview<\/a>.<\/p>\n\n\n\n

\"Tolinku\nThe webhooks page with create form, webhook list, and delivery log.<\/em><\/p>\n\n\n\n

The Four Categories of Webhook Failures<\/h2>\n\n\n\n

Almost every webhook issue falls into one of four buckets:<\/p>\n\n\n\n

    \n
  1. Delivery failures.<\/strong> The request never reaches your server. DNS issues, firewall rules, TLS errors, or your server being down.<\/li>\n
  2. Signature mismatches.<\/strong> The request arrives but your verification code rejects it. Usually caused by body parsing issues or incorrect secrets.<\/li>\n
  3. Payload parsing errors.<\/strong> The signature checks out but your handler crashes trying to process the payload. Missing fields, unexpected types, or encoding problems.<\/li>\n
  4. Timeouts.<\/strong> Your server receives the request but takes too long to respond. The sending platform marks the delivery as failed and retries.<\/li>\n<\/ol>\n\n\n\n

    Knowing which category you are dealing with cuts your debugging time significantly. The Tolinku dashboard's delivery log<\/a> shows the HTTP status code and response time for every delivery attempt, which tells you immediately whether the problem is on the network side (category 1), in your application logic (categories 2-3), or a performance issue (category 4).<\/p>\n\n\n\n

    Setting Up Local Development<\/h2>\n\n\n\n

    The biggest obstacle to debugging webhooks is that you cannot receive them on localhost<\/code>. The sending platform needs a publicly reachable URL. There are several tools that solve this by creating tunnels from the public internet to your local machine.<\/p>\n\n\n\n

    ngrok<\/h3>\n\n\n\n

    ngrok<\/a> is the most widely used option. Install it, then run:<\/p>\n\n\n\n

    ngrok http 3000\n<\/code><\/pre>\n\n\n\n
    This gives you a public URL like https:\/\/abc123.ngrok-free.app<\/code> that forwards to your local port 3000. Copy that URL into the Tolinku dashboard as your webhook endpoint.<\/p>\n\n\n\n
    ngrok also provides a local inspection UI at http:\/\/127.0.0.1:4040<\/code> where you can see every request, replay failed deliveries, and inspect headers and bodies. This inspection interface alone makes it worth using during development.<\/p>\n\n\n\n
    Webhook.site<\/h3>\n\n\n\n
    Webhook.site<\/a> gives you a temporary public URL that logs incoming requests. It is useful when you want to inspect raw payloads without writing any code. You can see the exact headers, body, and timing of each delivery. The limitation is that it does not forward to your local server, so it is better for inspection than for end-to-end testing.<\/p>\n\n\n\n
    Other Tunnel Options<\/h3>\n\n\n\n
    Cloudflare Tunnel<\/a> provides a free tunnel option that works well for longer-lived development environments. localtunnel<\/a> is an open-source alternative if you want to avoid creating accounts.<\/p>\n\n\n\n
    Whichever tool you use, the workflow is the same: start your local server, create a tunnel, register the tunnel URL in your Tolinku Appspace's webhook settings<\/a>, and trigger test events.<\/p>\n\n\n\n
    Using Test Deliveries<\/h2>\n\n\n\n
    Before debugging with real events, use Tolinku's test delivery feature. In the webhooks page of your Appspace dashboard, each endpoint has a "Send Test" option. This sends a sample payload to your endpoint and reports the result immediately.<\/p>\n\n\n\n
    Test deliveries are valuable for two reasons. First, they confirm basic connectivity: can the platform reach your endpoint at all? Second, they provide a known-good payload. If your handler works with a test delivery but fails on real events, the problem is in your event-specific processing logic, not in the plumbing.<\/p>\n\n\n\n
    If a test delivery fails, check the delivery log for the HTTP status code. A 000<\/code> or connection error means the platform could not reach your URL. A 4xx<\/code> or 5xx<\/code> means your server received the request but responded with an error.<\/p>\n\n\n\n
    Debugging Signature Mismatches<\/h2>\n\n\n\n
    Signature verification is where most webhook debugging happens. Tolinku signs every webhook delivery using HMAC-SHA256 over the raw request body. The signature is sent in the X-Webhook-Signature<\/code> header, and the event type is in the X-Webhook-Event<\/code> header.<\/p>\n\n\n\n
    Here is a correct verification implementation:<\/p>\n\n\n\n
    const crypto = require('crypto');\n\nfunction verifyWebhookSignature(req, secret) {\n  const signature = req.headers['x-webhook-signature'];\n\n  if (!signature) {\n    return false;\n  }\n\n  \/\/ Sign the raw request body (not parsed JSON)\n  const expected = crypto\n    .createHmac('sha256', secret)\n    .update(req.body) \/\/ req.body is a Buffer from express.raw()\n    .digest('hex');\n\n  const sig = Buffer.from(signature, 'hex');\n  const exp = Buffer.from(expected, 'hex');\n\n  if (sig.length !== exp.length) return false;\n\n  return crypto.timingSafeEqual(sig, exp\n  );\n}\n<\/code><\/pre>\n\n\n\n
    The most common cause of signature failures is body parsing<\/strong>. If you use express.json()<\/code> before your webhook route, Express parses the body into a JavaScript object, and the raw bytes are gone. The HMAC is computed over the raw request body, so you need to preserve it.<\/p>\n\n\n\n
    The fix is to capture the raw body during parsing:<\/p>\n\n\n\n
    app.use('\/webhooks', express.json({\n  verify: (req, res, buf) => {\n    req.rawBody = buf.toString('utf-8');\n  }\n}));\n<\/code><\/pre>\n\n\n\n
    Other common signature issues:<\/p>\n\n\n\n