Webhook verification handshake

Before Meta sends any events, it verifies that your callback URL is yours. This is a one-time GET handshake. Callduck handles it automatically once your verify token matches.

What Meta sends

When you save the callback URL in Meta's dashboard, Meta calls your endpoint with three query parameters:

• hub.mode=subscribe
• hub.verify_token=<the token you configured>
• hub.challenge=<a random string>

How Callduck responds

1. Callduck loads the channel from the URL's {channelId}.
2. It compares hub.verify_token against the channel's verify token (falling back to the WHATSAPP_VERIFY_TOKEN env value).
3. If hub.mode is subscribe and the token matches, Callduck echoes the raw hub.challenge back with HTTP 200 and Content-Type: text/plain.
4. If the token does not match, Callduck returns 403 and Meta marks verification as failed.

What success looks like

> In Meta's WhatsApp Configuration panel, the callback URL flips to Verified (a green check). If it fails, the token on both sides does not match — the #1 cause. Re-check the value in Callduck (Channels → WhatsApp), in Meta's webhook config, and in your WHATSAPP_VERIFY_TOKEN env.

See Verify token and Webhook callback URL.