App secret & webhook signatures

The app secret is your Meta app's private key. Callduck uses it to confirm that an incoming webhook really came from Meta and wasn't forged. It is separate from the verify token (which is only used for the one-time subscription handshake) and from your access token.

What it is and where to find it

Each Meta app has one app secret. Find it in Meta for Developers → your App → App settings → Basic → App secret (click Show). Add it to the channel under Channels → WhatsApp (or via WHATSAPP_APP_SECRET). Callduck stores it encrypted at rest and never returns it to the browser unmasked.

How Callduck uses it

On every webhook POST, Meta includes an X-Hub-Signature-256 header — an HMAC-SHA256 of the exact raw request body, keyed by your app secret, formatted as sha256=<hex>. Callduck:

1. Reads the raw body and the X-Hub-Signature-256 header.
2. Computes sha256= + HMAC-SHA256(rawBody, appSecret).
3. Compares the two with a constant-time check (timingSafeEqual). A mismatch means the payload is rejected as untrusted.

Enforcement depends on mode and environment

• Cloud API / BSP channel with an app secret, in production: a missing or invalid signature is hard-rejected with HTTP 401, and a webhook.signature_invalid audit entry is written. Forged payloads never touch your data.
• Cloud API / BSP channel with an app secret, non-production: the request is acknowledged but skipped so local testing stays easy.
• Demo / Mock channels: flexible — a signature is verified only if both an app secret and a signature are present.

Honest notes

• If you don't set an app secret, Callduck cannot verify signatures — set one for any real channel.
• A signature mismatch in production almost always means the channel's app secret doesn't match the Meta app's secret. Re-copy it from Meta and re-check WHATSAPP_APP_SECRET.
• The verify token and the app secret are different secrets for different jobs: the verify token authenticates the GET handshake; the app secret authenticates each POST payload.

See Webhook setup, Verify token, and Common Meta API errors.