Developer reference

Build securely from day one

The public portal explains the integration. Your private backend should own credentials, business identifiers, event processing, and audit trails.

Token and credential boundaries

  1. The browser may start a hosted Meta flow, but must not receive app secrets, long-lived tokens, system-user tokens, or private client identifiers.
  2. The backend exchanges and stores credentials in server-side secret storage with least-privilege access, rotation, expiry, and revocation ownership.
  3. Use separate development, staging, and production credentials/endpoints. Never copy production tokens into screenshots, issues, or chat.
  4. Return only the minimum safe result to the browser; keep raw provider responses and credential metadata restricted and redacted.

Webhook verification runbook

  1. Verify the challenge with the configured verify token.
  2. Read raw request bytes, calculate the expected signature with the app secret, and compare in constant time.
  3. Reject missing, malformed, stale, or invalid signatures before parsing or queuing.
  4. Persist an idempotency key/event ID, acknowledge quickly, and process with a retry-safe queue.
  5. Alert on signature failures, event spikes, repeated retries, and dead-letter items.

Testing matrix

  1. Verify webhook challenge and signature handling.
  2. Send controlled test messages and confirm delivery status events.
  3. Test duplicate events, retries, timeouts, invalid payloads, and revoked access.
  4. Confirm templates, opt-out handling, and escalation ownership.
  5. Remove test identifiers from production logs and screenshots.

Production checklist

  • HTTPS, signature validation, rate limits, and bounded retries.
  • Structured logs with event IDs—not private message content by default.
  • Separate environments, secret rotation, and documented revocation.
  • Monitoring for auth errors, webhook failures, queue backlog, and API limits.
  • Incident owner, rollback path, support runbook, and client handoff.
  • Redacted evidence only in support requests.

Reference links

Meta WhatsApp Cloud API documentation
Meta Marketing API overview