> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Setup

> Configure Meta to send WhatsApp events to your Switchbord instance — callback URL, signing secret, verify token, and field subscriptions.

# 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.

<Warning>
  Complete the [Connect WhatsApp](/platform/connect-whatsapp) guide first. You need a Meta App
  with WhatsApp added and a WABA ID before configuring webhooks.
</Warning>

***

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Configure the callback URL in Meta">
    In [Meta for Developers](https://developers.facebook.com), open your app and go to:

    **WhatsApp → Configuration → Webhook**

    Click **Edit** and set:

    * **Callback URL:**

      ```
      https://api.switchbord.ai/webhooks/meta?w={your-workspace-id}
      ```

      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.

    <Tip>
      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
    </Tip>
  </Step>

  <Step title="Subscribe to webhook fields">
    After saving the callback URL, scroll down to **Webhook fields** and click **Manage**.

    Subscribe to the following fields:

    | Field      | Purpose                                            |
    | ---------- | -------------------------------------------------- |
    | `messages` | Inbound messages, delivery statuses, read receipts |

    Click **Done**.

    <Note>
      You only need `messages` for core inbox operation. Additional fields like `message_template_status_update`
      can be added later for template sync notifications.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](https://developers.facebook.com), 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**.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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
  </Step>
</Steps>

***

## 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:

```
https://api.switchbord.ai/webhooks/meta?w=<workspace-uuid>
```

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

| Setting                | Where to find it                                                 | Where to enter it                                             |
| ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- |
| Callback URL           | Constructed from your workspace ID (see above)                   | Meta App → WhatsApp → Configuration → Webhook                 |
| Verify token           | You generate this                                                | Both Meta (webhook config) and Switchbord Settings → Provider |
| Webhook signing secret | Meta App → App Settings → Basic → App Secret                     | Switchbord Settings → Provider → Channel                      |
| WABA ID                | Meta Business Settings → Accounts → WhatsApp Accounts → Settings | Switchbord Settings → Provider → Channel                      |
| Phone Number ID        | Meta App → WhatsApp → API Setup                                  | Switchbord Settings → Provider → Channel                      |
| System User token      | Meta Business Settings → System Users                            | Switchbord Settings → Provider → Channel                      |

***

## 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](/operations/runbook) for escalation steps.

***

## Related Guides

* [Connect WhatsApp](/platform/connect-whatsapp) — full credential setup including WABA ID, phone number, and System User token
* [Meta Credential Setup](/operations/meta-credential-setup) — detailed guide for System User tokens and Business Portfolio setup
* [Webhook Operations](/operations/webhooks) — internal webhook model, envelope schema, and replay tooling