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

# Webhooks

> Visão geral dos eventos de webhook de entrada — para que servem, onde configurá-los e como se encaixam na superfície de integração do Switchbord.

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](/pt-BR/operations/webhooks) e [Configuração de webhook](/pt-BR/platform/webhook-setup).

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

<CardGroup cols={2}>
  <Card title="Endpoint gerado" icon="link">
    Cada configuração de webhook recebe sua própria URL em `/api/v1/inbound-webhooks/{slug}` — sem segredo compartilhado entre as configurações.
  </Card>

  <Card title="Mapeamento de template" icon="table-cells">
    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.
  </Card>
</CardGroup>

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

<Warning>
  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](/pt-BR/guides/webhook-dry-run-rollout) para o status atual e o que fazer caso você precise de envios em produção hoje.
</Warning>

## 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](/pt-BR/api-reference/inbound-webhooks).

## 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](/pt-BR/features/inbox) em primeiro lugar. Essa é uma etapa de configuração única, coberta em [Configuração de webhook](/pt-BR/platform/webhook-setup), e o modelo operacional por trás disso (armazenamento de envelope, verificação, replay) está documentado em [Operações de webhook](/pt-BR/operations/webhooks).

## Veja também

* [Configuração de webhook](/pt-BR/platform/webhook-setup) — como configurar a Meta para entregar eventos do WhatsApp ao seu workspace.
* [Operações de webhook](/pt-BR/operations/webhooks) — o modelo interno de envelope, monitoramento e ferramentas de replay.
* [Webhooks de entrada](/pt-BR/api-reference/inbound-webhooks) — a referência completa de autenticação e mapeamento para suas próprias integrações.
* [Lançamento do dry-run de webhook de entrada](/pt-BR/guides/webhook-dry-run-rollout) — status atual de promoção e etapas de teste seguras.