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

See also: Webhook Security, Webhook Examples