Webhooks entrantes

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:

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.

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:

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:

{
  "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 para envios em produção hoje.

Referência da API

Padrões de segurança

Endpoint

Autenticação

Mapeamento

Logs de execução

Limitação atual

Guias de integração

​Padrões de segurança

​Endpoint

​Autenticação

​Mapeamento

​Logs de execução

​Limitação atual

​Guias de integração

Padrões de segurança

Endpoint

Autenticação

Mapeamento

Logs de execução

Limitação atual

Guias de integração