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

# Configuração de Webhook

> Configure a Meta para enviar eventos do WhatsApp à sua instância do Switchbord — callback URL, signing secret, verify token e assinaturas de campos.

# Configuração de Webhook

Webhooks são a forma como a Meta entrega toda mensagem de entrada, status de entrega e atualização de template ao Switchbord. Sem um webhook configurado corretamente, sua caixa de entrada não receberá mensagens.

Este guia cobre os passos exatos para configurar webhooks da Meta — seja você usando a plataforma hospedada em `app.switchbord.ai` ou uma instância self-hosted.

<Warning>
  Complete primeiro o guia [Conectar WhatsApp](/pt-BR/platform/connect-whatsapp). Você precisa de um Meta App
  com o WhatsApp adicionado e um WABA ID antes de configurar webhooks.
</Warning>

***

## Como Funciona

Quando um usuário envia uma mensagem para o seu número do WhatsApp, a Meta chama sua webhook URL com o payload do evento. O Switchbord:

1. Verifica a assinatura usando seu App Secret
2. Armazena o envelope bruto no Supabase
3. Roteia o evento para a caixa de entrada do operador em tempo real

O parâmetro de query `?w=` na webhook URL informa ao Switchbord a qual workspace o evento pertence. É assim que o multi-tenancy funciona — cada workspace tem uma callback URL única.

***

## Configuração Passo a Passo

<Steps>
  <Step title="Encontre seu Workspace ID">
    No Switchbord, acesse **Settings → General**. Copie seu **Workspace ID** — é um UUID que se parece com `a1b2c3d4-...`.

    Você anexará isso à webhook callback URL na próxima etapa.
  </Step>

  <Step title="Configure a callback URL na Meta">
    No [Meta for Developers](https://developers.facebook.com), abra seu app e acesse:

    **WhatsApp → Configuration → Webhook**

    Clique em **Edit** e defina:

    * **Callback URL:**

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

      Substitua `{your-workspace-id}` pelo UUID da etapa anterior.

      Para instâncias self-hosted, substitua `api.switchbord.ai` pelo seu próprio domínio de API.

    * **Verify token:** Uma string que você escolhe. Você também vai inserir isso nas Settings do Switchbord. Use uma string aleatória — por exemplo, `openssl rand -hex 20` em um terminal.

    Clique em **Verify and save**. A Meta enviará imediatamente uma requisição de desafio para sua callback URL. O Switchbord responde automaticamente se a URL e o verify token estiverem corretos.

    <Tip>
      Se a verificação falhar, verifique se:

      * A callback URL está acessível pela internet (não `localhost`)
      * O parâmetro `?w=` contém o UUID exato do seu workspace
      * O verify token corresponde ao que você definiu nas Settings do Switchbord
    </Tip>
  </Step>

  <Step title="Assine os campos de webhook">
    Após salvar a callback URL, role para baixo até **Webhook fields** e clique em **Manage**.

    Assine os seguintes campos:

    | Campo      | Finalidade                                                       |
    | ---------- | ---------------------------------------------------------------- |
    | `messages` | Mensagens de entrada, status de entrega, confirmações de leitura |

    Clique em **Done**.

    <Note>
      Você só precisa de `messages` para a operação básica da caixa de entrada. Campos adicionais como `message_template_status_update`
      podem ser adicionados depois para notificações de sincronização de templates.
    </Note>
  </Step>

  <Step title="Defina o verify token no Switchbord">
    No Switchbord, acesse **Settings → Provider → Channel**.

    Insira o **Verify token** — a mesma string que você usou na configuração do webhook da Meta.

    Salve as configurações.
  </Step>

  <Step title="Defina o signing secret do webhook">
    O signing secret é o seu **Meta App Secret**. O Switchbord o usa para verificar o cabeçalho `X-Hub-Signature-256` em cada webhook recebido — se a assinatura não corresponder, o payload é rejeitado.

    **Encontre seu App Secret:**

    No [Meta for Developers](https://developers.facebook.com), abra seu app → **App Settings → Basic**.

    Clique em **Show** ao lado de **App secret** e copie o valor.

    No Switchbord, acesse **Settings → Provider → Channel** e insira o App Secret como o **Webhook signing secret**.

    <Warning>
      Nunca exponha seu App Secret em código client-side, arquivos de variáveis de ambiente commitados no git,
      ou em logs. É um segredo exclusivo do servidor. No Switchbord, ele é armazenado no Supabase Vault.
    </Warning>
  </Step>

  <Step title="Verifique se a configuração está funcionando">
    Envie uma mensagem de teste para o seu número do WhatsApp a partir de um telefone real. Depois:

    1. Abra o Switchbord → **Inbox** — a mensagem deve aparecer em poucos segundos
    2. Abra o Switchbord → **Operations** — procure por uma entrada recente de webhook com status `verified`

    Se a mensagem não aparecer:

    * Verifique a página Operations em busca de webhooks rejeitados (um status vermelho significa que a verificação de assinatura falhou)
    * Confirme que o App Secret nas Settings corresponde ao das Meta App Settings → Basic
    * Confirme que seu número do WhatsApp está em **Live mode** (não em Development) — o modo Development só recebe mensagens de testers
  </Step>
</Steps>

***

## Por Que o Parâmetro `?w=` É Importante

O Switchbord é multi-tenant. Múltiplos workspaces podem compartilhar um único deployment de API, cada um com seu próprio número do WhatsApp e credenciais.

O parâmetro `?w=` é como o Switchbord roteia o webhook de entrada para o workspace correto. Sem ele, o ingress de webhook não consegue determinar a qual workspace atribuir o evento e rejeitará o payload.

Cada workspace recebe sua própria callback URL:

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

Isso significa que, se você gerencia múltiplos números de WhatsApp em diferentes workspaces, cada workspace tem uma webhook URL distinta na Meta — mesmo que todas apontem para o mesmo host `api.switchbord.ai`.

***

## Referência de Credenciais

| Configuração           | Onde encontrar                                                   | Onde inserir                                                                      |
| ---------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Callback URL           | Construída a partir do seu workspace ID (veja acima)             | Meta App → WhatsApp → Configuration → Webhook                                     |
| Verify token           | Você mesmo gera                                                  | Tanto na Meta (configuração de webhook) quanto nas 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                                          |

***

## Solução de Problemas

**A verificação do webhook falha imediatamente**

* Garanta que a API esteja acessível publicamente. `localhost` não vai funcionar — use um túnel (ngrok, Cloudflare Tunnel) para desenvolvimento local.
* A callback URL deve incluir o parâmetro `?w=` com um UUID de workspace válido.
* O verify token na Meta deve corresponder exatamente ao das Switchbord Settings.

**Mensagens não aparecem na caixa de entrada**

* Verifique **Operations** em busca de rejeições de webhook. Um erro `signature_mismatch` significa que o App Secret no Switchbord não corresponde ao da Meta.
* Certifique-se de que o campo `messages` está assinado no gerenciador de campos de webhook da Meta.
* Confirme que o número de telefone está em **Live mode**, não em modo Development.

**Falhas intermitentes de entrega**

* A Meta reenvia webhooks que falharam. Se sua API esteve temporariamente inacessível, os eventos serão reproduzidos automaticamente.
* Verifique a página Operations em busca de uma fila de reproduções pendentes.
* Veja o [Runbook de Operações](/pt-BR/operations/runbook) para etapas de escalonamento.

***

## Guias Relacionados

* [Conectar WhatsApp](/pt-BR/platform/connect-whatsapp) — configuração completa de credenciais, incluindo WABA ID, número de telefone e token de System User
* [Configuração de Credenciais da Meta](/pt-BR/operations/meta-credential-setup) — guia detalhado para tokens de System User e configuração de Business Portfolio
* [Operações de Webhook](/pt-BR/operations/webhooks) — modelo interno de webhook, esquema de envelope e ferramentas de replay