Conversa Labs Help Center
en
Language
pt_BR Portuguese (Brazil) en English es Spanish

WhatsApp Cloud with a manual webhook from the Meta App Dashboard

Open in
View as Markdown Open in ChatGPT Open in Claude
Conversa Labs

Conversa Labs

Last updated on Jul 16, 2026

Overview

Besides Embedded Signup (Meta's guided login), the WhatsApp Cloud channel can also be connected in manual mode: you provide the credentials of your own Meta app (API key, Phone Number ID and Business Account ID) and configure the webhook directly in the Meta App Dashboard (WhatsApp → Configuration → Webhook). This mode is ideal when you already own a Meta app, need full control over the webhook subscriptions, or use a token with limited permissions.

The platform provides a single app-level callback URL that serves all your numbers and WhatsApp Business Accounts (WABAs): each event is routed automatically from the payload contents. A per-number URL is also available if you prefer to configure numbers individually.

Prerequisites

  • An administrator profile on the platform.
  • A Meta app with the WhatsApp product enabled and access to the App Dashboard.
  • The number's API key (permanent access token), Phone Number ID and Business Account ID.
  • Optional but strongly recommended: the Meta app's App Secret (App settings → Basic), used to validate the X-Hub-Signature-256 signature of every incoming webhook.

Step by step

  1. In Settings → Inboxes, create a new inbox and choose WhatsApp.
  2. Select the WhatsApp Cloud provider (manual mode, without the Meta login).
  3. Fill in the inbox name, phone number, Phone Number ID, Business Account ID and API key.
  4. (Recommended) Provide the App Secret to enable webhook signature verification.
  5. Choose whether the platform should register the webhook automatically via the Graph API. Disable it if you prefer to configure the webhook manually in the Meta App Dashboard.
  6. After creating the inbox, the screen shows the callback URL (app-level and per-number) and the verify token, with copy buttons.
  7. In the Meta App Dashboard, open WhatsApp → Configuration → Webhook, paste the callback URL and the verify token and click Verify and save.
  8. Subscribe the webhook fields: at least messages; we recommend also subscribing the template, number quality, account and security fields to receive administrative events in real time.
  9. Send a test message to the number and confirm it lands in the inbox.

Settings & options

  • Account Health tab (inbox Settings → Account health): shows the manual webhook panel with the URL, the token (masked, with reveal/copy), the registration status, the signature verification (HMAC) state and the registration mode (automatic or manual).
  • Re-subscribe: re-registers the webhook via the Graph API (available when auto-register is on).
  • Rotate token: generates a new verify token. In manual mode, paste the new value into the Meta App Dashboard after rotating.
  • Recent account events: the same tab lists the latest administrative events received — template status, number quality, account alerts, business capability and security — with severity badges.

Use cases

  • Companies with their own Meta app that don't want (or can't) use Embedded Signup.
  • Operations with multiple numbers and WABAs on the same Meta app: a single callback URL serves them all; multi-entry event batches are processed in full.
  • Tokens with limited permissions (without whatsapp_business_management): with auto-register disabled, the platform never calls Meta's subscription APIs.

Tips, limits & best practices

  • Always configure the App Secret: without it, webhooks are accepted without signature verification (the platform logs a warning). The installation operator can enforce signatures on every inbox globally.
  • Subscribe the template and quality fields in the App Dashboard: template statuses (approved/rejected/paused) then reflect on the platform in real time, without waiting for the periodic sync.
  • If the Meta Dashboard rejects a webhook field, save with a smaller set — the indispensable minimum is messages.
  • When rotating the token with auto-register disabled, remember to update the value in the Meta App Dashboard, otherwise the webhook verification fails on the next validation.

Troubleshooting

  • "Verify and save" fails on Meta: check that the callback URL was copied in full and that the verify token matches exactly what the platform shows (no spaces).
  • Messages don't arrive: confirm the messages field is subscribed in the App Dashboard and the number isn't listed as inactive by the operation.
  • Webhook flagged as mismatched in the Account Health tab: the URL registered on Meta differs from the expected one — use Re-subscribe (auto-register) or fix the URL manually in the App Dashboard.
  • Administrative events don't show up: the corresponding fields (templates, quality, account, security) must be subscribed on the Meta app's webhook.

See also