Test webhook delivery
Verify the complete connection and diagnose failures safely.
Reviewed
Start with webhook setup and the SDK receiver example.
Check the complete setup
- Confirm Send test succeeds and the signed test event is stored.
- If keeping Logic Flow, select Observe messages from all origins and save. Observation does not change who replies.
- Send a fresh message from an authorized test sender to the selected business number. Confirm it appears in Waaru Inbox and produces one durable
message.receivedrow. - If your server must reply, deliberately select Use your server, create a number-bound API key with the needed message scopes, and resolve any retained flow work. A human-owned chat must be explicitly released to API before an API reply. Follow the SDK send sequence.
- Reconcile a send's message ID through SDK/API reads and its
message.sent/message.deliveredevents. Queued acceptance is not delivery; read events depend on recipient behavior. - Test a repeated event and a temporary storage failure. Duplicate admission must not repeat business work, and a failed durable write must return
5xxrather than success.
Developer callbacks are separate from MCP incoming-message events. A working Developer webhook does not prove an MCP subscription is enabled or that an AI client received an event.
Troubleshoot setup and delivery
| Symptom | What to check |
|---|---|
502 webhook_verification_failed | The receiver must accept an unsigned POST and return only { "challenge": "…" } within the timeout. Check authentication middleware, an offline tunnel, redirects, TLS and HTML/error responses. The activation request has no signing secret. This failure preserves the configuration. |
Proxy or Cloudflare 502 without a Waaru application code | The application response was not completed through the proxy. Check whether your receiver saw a challenge, inspect Waaru delivery health, and read current webhook settings before retrying an uncertain creation. Share the time and request/ray ID with support, without secrets. |
| Test event fails signature verification | Use the webhook signing secret, not an API key or Meta app secret. Preserve exact raw bytes, check your clock, and load the current secret after rotation. |
| Test succeeds but no real inbound event arrives | Check the selected number, selected events and observation coverage. Logic Flow can stay active with all-origin observation enabled. Media ingestion can delay a callback. |
| A callback arrives more than once | Deduplicate by event ID after signature verification. Multiple status events for one message are different events; do not deduplicate them by message ID. |
| API reply is blocked while callbacks work | Delivery grants no reply authority. Check API-key scopes, number handler, human ownership, customer-service window and recipient restrictions. |
| Endpoint is paused or disabled | Repair the endpoint, read its latest revision, and explicitly resume it. Resume is not historical replay; reconcile current messages and retained changes. |
For help, share the environment, approximate time, event type, safe error code and request ID. Never include API keys, signing secrets, authorization headers, full payloads or customer phone numbers.