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

> Configure webhooks entrantes protegidos por HMAC que mapeiam eventos externos para envios transacionais de template.

Os webhooks entrantes permitem que um workspace receba eventos de sistemas externos e os mapeie para o contrato de envio transacional de template do Switchbord.

## Padrões de segurança

Novas configurações de webhook são desabilitadas e configuradas em modo dry-run (execução simulada) por padrão. Um dry-run registra a execução entrante, verifica a assinatura, valida o mapeamento e armazena a requisição transacional mapeada, sem enfileirar um envio real.

Os segredos são gerados uma única vez. O Switchbord armazena apenas um hash SHA-256 e um prefixo curto para exibição. As respostas de listagem nunca incluem o segredo bruto. Após a criação, nunca envie o segredo bruto para o Switchbord; use-o apenas para produzir assinaturas de requisição.

## Endpoint

Cada configuração recebe uma URL gerada:

```text theme={null}
POST /api/v1/inbound-webhooks/{slug}
```

O endpoint resolve o workspace e a configuração de webhook a partir do slug da URL. Os campos do payload nunca são confiáveis para a resolução de tenancy.

## Autenticação

As requisições devem incluir uma assinatura HMAC com timestamp sobre o corpo bruto exato da requisição. Não inclua o segredo bruto do webhook em headers, parâmetros de query ou no payload.

```text theme={null}
X-Switchbord-Signature: t=<timestamp unix em segundos>,v1=<hmac sha256 em hex>
Idempotency-Key: optional-external-event-id
```

O `v1` HMAC assina `{timestamp}.{rawBody}` com o segredo único gerado quando o webhook foi criado. Os timestamps devem estar dentro de cinco minutos do relógio do Switchbord, para reduzir o risco de replay. Múltiplas entradas `v1` são aceitas para que remetentes possam tentar novamente durante a rotação de chaves, mas pelo menos uma deve corresponder.

Exemplo de geração de assinatura:

```ts theme={null}
import { createHash, createHmac } from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000);
const secretHash = createHash("sha256").update(secret).digest("hex");
const digest = createHmac("sha256", secretHash)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const signature = `t=${timestamp},v1=${digest}`;
```

A verificação de assinatura usa uma comparação segura contra timing (timing-safe) e ocorre antes do mapeamento ou do enfileiramento.

## Mapeamento

O construtor em Settings é a forma recomendada de criar mapeamentos. Ele carrega templates Utility aprovados, mostra as variáveis de body/button/header que cada template precisa, e permite mapear cada campo a partir de um caminho do payload, um valor literal ou um valor JSON.

Os mapeamentos em runtime suportam valores legados de dot-path e expressões explícitas:

```json theme={null}
{
  "to": "path:customer.phone",
  "templateName": "literal:payment_receipt_document",
  "templateLocale": "literal:it",
  "externalId": "path:receipt.id",
  "parameters.header.document.link": "path:receipt.pdf",
  "parameters.header.document.filename": "literal:receipt.pdf",
  "parameters.body.1": "path:customer.first_name",
  "parameters.body.2": "path:receipt.number"
}
```

Prefixos de expressão:

| Prefixo     | Significado                                             |
| ----------- | ------------------------------------------------------- |
| `path:`     | Resolve um dot path a partir do payload JSON entrante.  |
| `literal:`  | Usa o texto após o prefixo como o valor.                |
| `json:`     | Interpreta o texto após o prefixo como JSON.            |
| sem prefixo | Busca legada por dot-path a partir do payload entrante. |

Os destinos de mapeamento não podem conter `__proto__`, `prototype` ou `constructor`. O Switchbord rejeita destinos inseguros antes de pré-visualizar ou processar o webhook.

Os valores configurados de `templateName` e `templateLocale` sobrescrevem os valores mapeados. Novas configurações criadas via Settings são restritas ao template Utility aprovado selecionado.

## Logs de execução

Toda requisição recebida para uma configuração habilitada registra uma execução com headers redigidos, metadados do formato do payload, diagnósticos sanitizados da requisição mapeada, status e erros. Payloads brutos de cliente, números de telefone de destinatários e valores de variáveis de template não são armazenados nos logs de execução por padrão. Assinaturas inválidas são registradas como execuções com falha e retornam `401`, mas não reservam chaves de idempotência verificadas.

Os status de execução possíveis incluem `verified`, `dry_run`, `queued`, `failed` e `skipped_duplicate`.

## Limitação atual

A base do runtime pode executar o serviço de envio transacional de template quando uma configuração está habilitada, mas as configurações criadas via Settings estão atualmente forçadas ao modo dry-run desabilitado e não podem ser promovidas por meio da API pública de Settings. Uma requisição assinada para uma configuração desabilitada retorna `404 webhook_not_found_or_disabled`. A promoção em produção está bloqueada no servidor até que um fluxo de promoção verificado por log de execução seja lançado. Use [Envios transacionais de template](/pt-BR/api-reference/transactional-template-sends) para envios em produção hoje.

## Guias de integração

* [Link de recibo de pagamento via botão de URL](/pt-BR/guides/receipt-link-webhook)
* [Recibo em PDF via header DOCUMENT](/pt-BR/guides/pdf-receipt-webhook)
* [Lançamento gradual de dry-run para webhooks entrantes](/pt-BR/guides/webhook-dry-run-rollout)