Lançamento em dry-run de webhook de entrada

Os webhooks de entrada são intencionalmente conservadores. Novas configurações são desabilitadas e em dry-run por padrão, e a promoção para produção fica bloqueada no servidor até que um fluxo de promoção verificado por run-log seja lançado. Use este guia para validar uma integração de webhook com segurança hoje e entender o que vai mudar quando a promoção para produção for habilitada.

Comportamento atual

Estágio	Suportado hoje	Comportamento
Criar config	Sim	Cria uma config desabilitada, em dry-run, e revela o segredo de assinatura uma única vez.
Preview guiado	Sim	Resolve mapeamentos de payload de exemplo no navegador sem enviar uma mensagem.
Requisição assinada para endpoint criado em Settings	Ainda não	Configs criadas em Settings estão desabilitadas; requisições assinadas retornam `404 webhook_not_found_or_disabled` até que os controles de promoção verificada sejam lançados.
Envio real a partir de webhook de entrada	A base já existe, promoção bloqueada em Settings/API	A execução em runtime está implementada para configs habilitadas, mas a promoção via Settings/API permanece bloqueada até que os controles de promoção verificada sejam lançados.
Interface de replay/promoção	Trabalho futuro	Rastreado separadamente sob observabilidade de webhooks e controles de lançamento.

Se você precisa de envios em produção imediatamente, use a API direta de Envios transacionais de templates com uma chave de API e uma chave de idempotência. Use webhooks de entrada hoje para validar o mapeamento no preview do navegador e para preparar o código de assinatura para a futura promoção dry-run do lado do servidor.

Passo 1: Criar o webhook

Abra Settings → Integrations → Webhooks & API.
Clique em Create webhook.
Selecione um template Utility aprovado.
Mapeie os campos obrigatórios.
Cole um payload de exemplo.
Clique em Run dry-run preview.
Crie o webhook somente depois que o preview passar.

O Switchbord exibe o segredo de assinatura uma única vez. Copie-o imediatamente e armazene-o no cofre de segredos do sistema externo.

Passo 2: Preparar requisições assinadas

Você pode preparar o remetente externo agora, mas as configs de webhook criadas em Settings estão desabilitadas hoje. Uma requisição para a URL gerada retornará 404 webhook_not_found_or_disabled até que os controles de promoção verificada sejam lançados. Use exatamente o corpo JSON bruto ao gerar a assinatura.

import { createHash, createHmac } from "node:crypto";

const payload = {
  customer: { phone: "+393331234567", first_name: "Giulia" },
  receipt: {
    id: "payment-receipt-R-1001",
    number: "R-1001",
    amount: "€ 240,00",
    pdf: "https://cdn.example.com/receipts/R-1001.pdf"
  }
};

const rawBody = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000);
const secretHash = createHash("sha256").update(webhookSecret).digest("hex");
const digest = createHmac("sha256", secretHash)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

await fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Switchbord-Signature": `t=${timestamp},v1=${digest}`,
    "Idempotency-Key": payload.receipt.id
  },
  body: rawBody
});

Passo 3: Inspecionar o preview do navegador hoje

Hoje, o passo de validação suportado é o preview no navegador do construtor. Um preview saudável:

resolve destinatário, template, variáveis de corpo, botões e cabeçalhos de documento
rejeita amostras JSON inválidas
rejeita destinos de mapeamento inseguros
rejeita links de documento que não sejam HTTPS
não envia uma mensagem de WhatsApp

Quando a promoção verificada por run-log for lançada, requisições dry-run assinadas vão adicionar run logs do lado do servidor com signatureValid: true, status dry_run, diagnósticos sanitizados da requisição mapeada, e nenhum armazenamento do payload bruto do cliente.

Passo 4: Migrar para envios em produção

Até que a promoção para produção seja lançada em Settings/API, use a API direta para envios em produção:

POST /api/v1/template-sends

Quando a promoção para produção for lançada, o checklist de promoção esperado será:

Pelo menos um dry-run assinado recente para a config tem signatureValid: true.
O dry-run resolveu todos os mapeamentos obrigatórios.
O template selecionado ainda é Utility aprovado.
O operador tem acesso developer/admin.
Os kill switches em nível de config e de workspace permitem a execução.
Os run logs permanecem sanitizados.

Falhas comuns no lançamento

Falha	Significado	Correção
`missing_timestamp`	O cabeçalho de assinatura não tem `t=`.	Adicione o timestamp em segundos Unix a `X-Switchbord-Signature`.
`expired_timestamp`	O relógio do remetente está fora da janela de replay de cinco minutos.	Sincronize o relógio com NTP e assine imediatamente antes de enviar.
`invalid_signature`	O digest não corresponde ao corpo bruto.	Assine exatamente os bytes brutos da requisição.
`webhook_not_found_or_disabled`	A config de webhook criada em Settings ainda está desabilitada.	Use o preview no navegador hoje; use a API direta para envios em produção até que a promoção seja lançada.
`invalid_mapping_target`	O destino do mapeamento inclui um segmento de caminho proibido.	Remova `__proto__`, `prototype` ou `constructor` das chaves de mapeamento.
`invalid_media_link`	A URL de documento/imagem é inválida ou não é HTTPS.	Use uma URL pública em HTTPS.
`template_not_approved_utility`	O template selecionado está ausente, oculto, não aprovado, ou não é Utility.	Sincronize/aprove um template Utility no workspace.

Primeiros passos

Funcionalidades

WhatsApp

Guias

Contribuindo

Plataforma

Operações

Segurança e Conformidade

Lançamento em dry-run de webhook de entrada

Comportamento atual

Passo 1: Criar o webhook

Passo 2: Preparar requisições assinadas

Passo 3: Inspecionar o preview do navegador hoje

Passo 4: Migrar para envios em produção

Falhas comuns no lançamento

Guias relacionados

​Comportamento atual

​Passo 1: Criar o webhook

​Passo 2: Preparar requisições assinadas

​Passo 3: Inspecionar o preview do navegador hoje

​Passo 4: Migrar para envios em produção

​Falhas comuns no lançamento

​Guias relacionados

Comportamento atual

Passo 1: Criar o webhook

Passo 2: Preparar requisições assinadas

Passo 3: Inspecionar o preview do navegador hoje

Passo 4: Migrar para envios em produção

Falhas comuns no lançamento

Guias relacionados