The demo worked on the first try: a message went out, a reply came back, everyone clapped. Then the integration went live, and the real questions arrived. Why did that customer get the same confirmation twice? Why did an entire tenant go silent over the weekend? Where exactly is the access token stored? This playbook is for the engineers who inherit a WhatsApp integration after launch and need it to stay boring, observable and secure.
Introduction
Most WhatsApp tutorials end at the first successful send; operations teams start there. First, know which access model you are actually running, because the failure modes differ: Meta’s WhatsApp Business Platform (the Cloud API, directly or through a Business Solution Provider) provisions a business number and enforces templates and messaging tiers, while a unified API connects an account a user already owns, the way WhatsApp Web does. This complete guide to the whatsapp api maps those paths in detail. Everything below applies to both, with a few notes where they diverge.
Treat inbound webhooks as an untrusted, at-least-once stream
Inbound messages, delivery receipts and read events reach you as webhooks, and three assumptions about them will hurt you in production: that every request is genuine, that each event arrives once, and that events arrive in order. None is guaranteed.
Start with authenticity. Meta signs Cloud API webhook payloads with an X-Hub-Signature-256 header, an HMAC of the raw body computed with your app secret. Verify it against the raw bytes before any JSON parsing, because re-serialized JSON will not match. If you consume webhooks from another provider, use whatever it offers (a shared secret header, a signature, an allow-listed source) and reject anything that fails the check with a quiet 401.
Then decouple receiving from processing. The webhook handler should do three things only: verify, write the raw event to a durable queue, and return a 2xx quickly. Providers retry when your endpoint is slow or failing, so a handler that calls your CRM, your database and a language model inline will time out under load and trigger retries that make the load worse. A queue (SQS, Pub/Sub, RabbitMQ, whatever your team already runs) absorbs spikes and lets workers retry independently.
Finally, make processing idempotent. Every message event carries a provider message ID. Store it with a unique constraint and skip anything you have already seen. This one table eliminates the classic production bug where a retried webhook produces a duplicate ticket, a duplicate CRM activity or, worst of all, a duplicate automated reply.
- Order events by provider timestamp, not arrival time, and let message state only move forward (a “read” event can arrive before “delivered”).
- Keep raw payloads for a short, defined retention period so you can replay a worker bug without asking anyone to resend anything.
Retries, backoff and rate limits on the outbound side
Outbound sends fail too, and the fix is the same discipline in reverse. Wrap every send in a job with a bounded retry policy and exponential backoff with jitter. Distinguish transient errors (timeouts, 5xx, rate limiting) from permanent ones (invalid recipient, template not approved, account disconnected) and never retry the second group, or you will burn quota and pollute your metrics.
On the Cloud API, Meta enforces a throughput ceiling, hourly request limits and a per-recipient pair rate, alongside the messaging tier that caps unique recipients per rolling 24 hours. Respect them in a central sender service rather than in each caller. With a linked user account, there is no published tier to read from, so pacing is your own policy: sending cadence and volume remain a customer-side decision, and the safe default is to keep traffic close to what a person would plausibly send.
Secrets, tokens and environment separation
A WhatsApp integration typically holds several secrets: the Cloud API access token (often a long-lived system user token), the app secret used for signature checks, any BSP credentials, and, for unified APIs, the provider API key. Each one can send messages as your company, so handle them like database root passwords.
- Store them in a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager), never in environment files committed to Git or baked into container images.
- Give staging and production different tokens, different apps and ideally different phone numbers or test accounts, so a staging load test can never message a real customer.
- Rotate on a schedule and on every departure from the team, and document the rotation steps before you need them at 2 a.m.
- Scrub tokens and phone numbers from logs. Message bodies are personal data under GDPR, so decide deliberately what your log pipeline keeps.
When evaluating a vendor that will hold these credentials and message content on your behalf, ask for its security posture in writing. Unipile, for example, operates under SOC 2 Type II and GDPR, which gives security reviewers something concrete to assess.
Account health is a first-class signal
Webhook failures are visible. Silent disconnections are not, and they are the incident that generates the angriest tickets. On the Cloud API, watch the phone number’s quality rating and template status changes, because a drop in quality can throttle your tier before anyone notices. With linked accounts, the main risk is a session ending: the user removes the linked device from their phone, reinstalls WhatsApp, or leaves the phone offline long enough for WhatsApp to log out linked devices.
Unipile exposes this as an account status, with a webhook that fires when an account moves from operational to a state that needs reauthentication. Wire that event into three places: an alert for your support team, an in-app banner asking the user to reconnect (a fresh QR code or pairing code), and a circuit breaker that pauses outbound jobs for that account so they fail fast instead of piling up in retries.
Monitoring, alerting and testing that reflect reality
Dashboards should answer operational questions, not just show request counts. A useful baseline:
- Webhook verification failures per minute (a spike means a misconfiguration or someone probing your endpoint).
- Queue depth and age of the oldest unprocessed event.
- Outbound success rate split by error class, plus retry volume.
- Accounts by status, with an alert when the disconnected share rises above its usual baseline.
- End-to-end latency from inbound webhook to the message appearing in your product.
For testing, Meta provides a test number and sandbox setup in the developer app for the Cloud API, which covers template and webhook flows without touching customers. For linked accounts, keep a small pool of dedicated test phones, connect them in staging, and run a synthetic check every few minutes that sends a message between two test accounts and asserts the inbound webhook arrives. That single canary will catch expired sessions, broken webhook routes and queue stalls before your users do.
A short runbook to finish the job
Write down the answers before the first incident: who can rotate each secret, how to replay events from the raw store, how to pause sending for one account or one tenant, how to tell a user to reconnect, and what the escalation path is when the provider itself is degraded. An integration that is idempotent, queued, observable and paced rarely makes headlines, which is exactly the goal.
