Skip to main content

​
Webhook Setup

Webhooks are how Meta delivers every inbound message, delivery status, and template update to Switchbord. Without a correctly configured webhook, your inbox will not receive messages. This guide covers the exact steps to configure Meta webhooks — whether you are using the hosted platform at app.switchbord.ai or a self-hosted instance.
Complete the Connect WhatsApp guide first. You need a Meta App with WhatsApp added and a WABA ID before configuring webhooks.

​
How It Works

When a user sends a message to your WhatsApp number, Meta calls your webhook URL with the event payload. Switchbord:
  1. Verifies the signature using your App Secret
  2. Stores the raw envelope in Supabase
  3. Routes the event to the operator inbox in real time
The ?w= query parameter on the webhook URL tells Switchbord which workspace the event belongs to. This is how multi-tenancy works — each workspace has a unique callback URL.

​
Step-by-Step Setup

1

Find your Workspace ID

In Switchbord, go to Settings → General. Copy your Workspace ID — it is a UUID that looks like a1b2c3d4-....You will append this to the webhook callback URL in the next step.
2

Configure the callback URL in Meta

In Meta for Developers, open your app and go to:WhatsApp → Configuration → WebhookClick Edit and set:
  • Callback URL:
    Replace {your-workspace-id} with the UUID from the previous step. For self-hosted instances, replace api.switchbord.ai with your own API domain.
  • Verify token: A string you choose. You will also enter this in Switchbord Settings. Use a random string — for example, openssl rand -hex 20 in a terminal.
Click Verify and save. Meta will immediately send a challenge request to your callback URL. Switchbord responds automatically if the URL and verify token are correct.
If verification fails, check that:
  • The callback URL is reachable from the internet (not localhost)
  • The ?w= parameter contains your exact workspace UUID
  • The verify token matches what you set in Switchbord Settings
3

Subscribe to webhook fields

After saving the callback URL, scroll down to Webhook fields and click Manage.Subscribe to the following fields:Click Done.
You only need messages for core inbox operation. Additional fields like message_template_status_update can be added later for template sync notifications.
4

Set the verify token in Switchbord

In Switchbord, go to Settings → Provider → Channel.Enter the Verify token — the same string you used in the Meta webhook configuration.Save the settings.
5

Set the webhook signing secret

The signing secret is your Meta App Secret. Switchbord uses it to verify the X-Hub-Signature-256 header on every incoming webhook — if the signature does not match, the payload is rejected.Find your App Secret:In Meta for Developers, open your app → App Settings → Basic.Click Show next to App secret and copy the value.In Switchbord, go to Settings → Provider → Channel and enter the App Secret as the Webhook signing secret.
Never expose your App Secret in client-side code, environment variable files committed to git, or log output. It is a server-only secret. In Switchbord, it is stored in Supabase Vault.
6

Verify the setup is working

Send a test message to your WhatsApp number from a real phone. Then:
  1. Open Switchbord → Inbox — the message should appear within a few seconds
  2. Open Switchbord → Operations — look for a recent webhook entry with status verified
If the message does not appear:
  • Check the Operations page for rejected webhooks (a red status means signature verification failed)
  • Confirm the App Secret in Settings matches the one in Meta App Settings → Basic
  • Confirm your WhatsApp number is in Live mode (not Development) — Development mode only receives messages from testers

​
Why the ?w= Parameter Matters

Switchbord is multi-tenant. Multiple workspaces can share a single API deployment, each with its own WhatsApp number and credentials. The ?w= parameter is how Switchbord routes the incoming webhook to the correct workspace. Without it, the webhook ingress cannot determine which workspace to assign the event to and will reject the payload. Each workspace gets its own callback URL:
This means if you manage multiple WhatsApp numbers across different workspaces, each workspace has a distinct webhook URL in Meta — even though they all point to the same api.switchbord.ai host.

​
Credential Reference

​
Troubleshooting

Webhook verification fails immediately
  • Ensure the API is publicly reachable. localhost will not work — use a tunnel (ngrok, Cloudflare Tunnel) for local development.
  • The callback URL must include the ?w= parameter with a valid workspace UUID.
  • The verify token in Meta must exactly match the one in Switchbord Settings.
Messages not appearing in inbox
  • Check Operations for webhook rejections. A signature_mismatch error means the App Secret in Switchbord does not match the one in Meta.
  • Make sure the messages field is subscribed in Meta’s webhook field manager.
  • Confirm the phone number is in Live mode, not Development mode.
Intermittent delivery failures
  • Meta retries failed webhooks. If your API was temporarily unreachable, events will be replayed automatically.
  • Check the Operations page for a queue of pending replays.
  • See the Operations Runbook for escalation steps.
  • Connect WhatsApp — full credential setup including WABA ID, phone number, and System User token
  • Meta Credential Setup — detailed guide for System User tokens and Business Portfolio setup
  • Webhook Operations — internal webhook model, envelope schema, and replay tooling