ClawNode
Webhooks not working? Debugging checklist
Webhook failures are usually one of a few repeat causes: unreachable URL, signature mismatch, invalid payload, or provider retries. Use this checklist top to bottom.
1
Confirm endpoint reachability
- Webhook URL must be public HTTPS, not localhost.
- DNS and TLS certificate must be valid.
- Firewall and proxy rules must allow inbound requests.
2
Validate request and signature
- Use the exact signing secret configured on the provider.
- Verify signature against raw request body.
- Check timestamp tolerance and replay protection logic.
3
Inspect logs and retries
- Compare provider delivery logs with your app logs.
- Return fast 2xx responses before heavy processing.
- Move expensive tasks to async queue workers.
4
Use a reproducible test payload
Save one real webhook payload and replay it locally and in staging to isolate whether the issue is network, auth, or business logic.