Skip to main content

​
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.
Complete primeiro o guia Conectar WhatsApp. Você precisa de um Meta App com o WhatsApp adicionado e um WABA ID antes de configurar webhooks.

​
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

1

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

Configure a callback URL na Meta

No Meta for Developers, abra seu app e acesse:WhatsApp → Configuration → WebhookClique em Edit e defina:
  • Callback URL:
    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.
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
3

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:Clique em Done.
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.
4

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

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, 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.
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.
6

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

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

​
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 para etapas de escalonamento.

​
Guias Relacionados