Skip to main content
O Switchbord usa webhooks em duas direções. A Meta envia webhooks para o Switchbord a cada mensagem do WhatsApp, status de entrega e atualização de template — é assim que sua caixa de entrada permanece ativa. Separadamente, o Switchbord pode receber webhooks dos seus próprios sistemas externos (uma plataforma de reservas, um processador de pagamentos, um CRM) e transformá-los em envios de saída pelo WhatsApp. Esta página cobre o segundo tipo — a superfície de integração que os operadores configuram. Esta é a introdução mais leve, voltada ao operador. Para o contrato técnico completo — esquema do envelope, formato da assinatura HMAC, ferramentas de replay — veja Operações de webhook e Configuração de webhook.

​
Para que servem os webhooks de entrada

Se um sistema externo precisa disparar uma mensagem do WhatsApp quando algo acontece em outro lugar — um recibo é gerado, um pedido é despachado, um agendamento é feito — você não precisa escrever código de integração personalizado. Você configura um endpoint de webhook no Switchbord, mapeia os campos do evento externo para as variáveis de um template aprovado, e o sistema externo faz um POST para esse endpoint sempre que o evento ocorre.

Endpoint gerado

Cada configuração de webhook recebe sua própria URL em /api/v1/inbound-webhooks/{slug} — sem segredo compartilhado entre as configurações.

Mapeamento de template

O construtor em Settings carrega seus templates de Utilidade aprovados e permite mapear cada variável a partir de um campo do payload, um valor literal ou um valor JSON.

​
Configurando um webhook

Os webhooks de entrada são configurados em Settings → Integrations → Webhooks & API:
  1. Clique em Create webhook.
  2. Selecione um template de Utilidade aprovado.
  3. Mapeie as variáveis do template para os campos no payload do seu sistema externo.
  4. Cole um payload de exemplo e execute a prévia de dry-run para confirmar que o mapeamento resolve corretamente — isso acontece inteiramente no navegador e nunca envia uma mensagem.
  5. Crie o webhook depois que a prévia for aprovada. O segredo de assinatura é exibido apenas uma vez — copie-o imediatamente para o cofre de segredos do seu sistema externo, já que o Switchbord só armazena um hash a partir desse momento.
Novas configurações de webhook são criadas desativadas e em modo dry-run por padrão, como medida de segurança. Um dry-run verifica a assinatura e valida o mapeamento sem colocar um envio real na fila. A promoção para produção de webhooks criados em Settings está atualmente bloqueada no servidor, aguardando controles de promoção verificados — veja o guia de lançamento do dry-run para o status atual e o que fazer caso você precise de envios em produção hoje.

​
Autenticando requisições

Toda requisição precisa carregar uma assinatura HMAC com timestamp sobre o corpo bruto da requisição, gerada com o segredo único exibido na criação. O Switchbord verifica isso com uma comparação segura contra timing antes de tocar no mapeamento ou colocar qualquer coisa na fila. O formato completo da assinatura e um exemplo de código funcional estão em Webhooks de entrada.

​
Os webhooks da Meta (a outra direção)

Separadamente, o seu número do WhatsApp precisa que a Meta esteja configurada para enviar seus webhooks para o Switchbord — é isso que faz as mensagens aparecerem na sua Inbox em primeiro lugar. Essa é uma etapa de configuração única, coberta em Configuração de webhook, e o modelo operacional por trás disso (armazenamento de envelope, verificação, replay) está documentado em Operações de webhook.

​
Veja também