Webhook Troubleshooting

What it is

Webhooks can fail for several reasons: signature verification, delivery timeouts, or incorrect URLs.

Signature verification failing

• Secret mismatch: The webhook secret in your endpoint must match the secret configured in WHMDC. Copy it exactly.
• Payload: Compute HMAC-SHA256 over the raw request body (as received), not a parsed/decoded version.
• Header: The signature is in X-Webhook-Signature header, typically prefixed with sha256=.

Delivery failures

• URL: Ensure the webhook URL is correct: https://yourdomain.com/your/webhook/endpoint. Must be HTTPS in production.
• Timeout: Your endpoint must respond within the gateway's timeout (often 30 seconds). Process asynchronously if needed.
• Logs: Check webhook logs in Admin (if available) for delivery status and error messages.
• Retry: Some gateways retry failed deliveries. Ensure your endpoint is idempotent (same event may be sent twice).

Local testing

Use ngrok or similar to expose your local server to the internet. Use the ngrok URL as the webhook URL in the gateway config. This lets you receive real webhook events during development.