Skip to main content

Webhook Troubleshooting

This page covers testing methods and solutions for common webhook integration issues.

Testing Your Webhook​

Console Test Request​

Use the "Test Request" button in the Console Webhooks section to send a test webhook payload to your endpoint. This is the quickest way to verify your server is reachable and responding correctly.

Send and Receive Messages​

Send or receive messages to your Agency phone number or email address. This triggers real webhook events and lets you validate the full end-to-end flow.

Staging Limitations​

Staging environments only support inbound channels. Use production webhooks or the Console test feature to validate outbound event handling.

Common Issues​

Signature Mismatch​

  • Ensure you are computing the HMAC-SHA256 on the raw request body, not a parsed and re-serialized version. Parsing and re-serializing JSON can change whitespace or key order, producing a different hash.
  • Verify the shared secret in your application matches the value configured in the Console.
  • Confirm the secret is 24 characters or fewer.

Timeout​

  • Return HTTP 200 immediately upon receiving the request.
  • Move any time-consuming processing (database writes, API calls, etc.) to a background job or queue.

IP Blocked​

  • Verify that the webhook IP addresses listed in the Console are added to your firewall or application-level allowlist.
  • If you are behind a CDN or load balancer, ensure the original client IP is forwarded correctly (check the X-Forwarded-For header).

No Events Received​

  • Confirm the webhook is enabled in the Console.
  • Verify the webhook URL is correct and publicly accessible from the internet.
  • Check that an Agency is assigned to the webhook if your configuration requires one.
  • Review your server logs for incoming requests that may be rejected before reaching your application logic.

See Also​