Webhooks

Webhooks are how Meta pushes events to Callduck — inbound messages, delivery/read receipts, and template status changes. Each channel has its own endpoint so events are always scoped to the right workspace.

Endpoints

• Per-channel callback: {YOUR_DOMAIN}/api/webhooks/whatsapp/{channelId}
• Health probe: {YOUR_DOMAIN}/api/webhooks/health (unauthenticated liveness check)

Two phases

1. Verification (GET) — Meta sends a one-time handshake with your verify token; Callduck echoes the challenge. See Webhook verification.
2. Events (POST) — Meta delivers message and status payloads, which Callduck parses into conversations and messages.

Security

When you set an app secret on the channel, Callduck verifies the X-Hub-Signature-256 header on each POST and ignores any payload whose signature does not match. The endpoint always returns 200 quickly so Meta does not retry-storm you, and tenant isolation is derived from the channel — never from the request body.

Subscribe the right fields

In Meta's WhatsApp → Configuration, subscribe at least messages and message_template_status_update. See Webhook callback URL for the full setup.