Skip to main content

Webhook Debugging

Step-by-step debugging for webhook issues.

Signature Mismatch (401)​

  1. Verify shared secret matches between Console and your application (max 24 characters)
  2. Compute HMAC-SHA256 on the raw request body (not parsed/re-serialized JSON)
  3. Use constant-time comparison (crypto.timingSafeEqual in Node.js)
  4. Check that X-ECD-Signature header is being read correctly

IP Blocked (403)​

  1. Get the webhook IP addresses from Console
  2. Add them to your firewall allowlist
  3. If behind a reverse proxy, check X-Forwarded-For header for the real client IP

No Events Received​

  1. Verify webhook is enabled and not paused in Console
  2. Check webhook URL is correct and publicly accessible (not localhost)
  3. Verify agency is assigned to the webhook
  4. Test with Console's "Test Request" button
  5. Check your server logs for incoming requests

Timeout Issues​

  1. Return HTTP 200 immediately upon receiving the webhook
  2. Process the payload asynchronously (queue, background job)
  3. Do not perform long-running operations in the request handler

Testing​

  • Use the Console "Test Request" button to send test payloads
  • Staging environments only support inbound channels
  • Use tools like ngrok to expose local development servers for testing

Getting Help​

To request help, create a support ticket in the Console: sign in, click the Help button in the bottom-right corner, and complete the Create a Ticket form (Region, Agency, Feature, and a Description). The page you are on is attached automatically, and you can follow updates under My Tickets in the same panel.

In the description, include the webhook name and URL, the response code your endpoint returned, whether the webhook is enabled and has an agency assigned, and the approximate time of the issue.

danger

Never share the webhook shared secret in a support ticket or logs.

See also: Webhook Security, Webhook Examples