> ## 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. # Lançamento em dry-run de webhook de entrada > Teste mapeamentos de webhook de entrada com segurança antes que os envios transacionais em produção sejam habilitados. 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](/pt-BR/api-reference/transactional-template-sends) 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 1. Abra **Settings → Integrations → Webhooks & API**. 2. Clique em **Create webhook**. 3. Selecione um template Utility aprovado. 4. Mapeie os campos obrigatórios. 5. Cole um payload de exemplo. 6. Clique em **Run dry-run preview**. 7. 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. ```ts theme={null} 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: ```text theme={null} POST /api/v1/template-sends ``` Quando a promoção para produção for lançada, o checklist de promoção esperado será: 1. Pelo menos um dry-run assinado recente para a config tem `signatureValid: true`. 2. O dry-run resolveu todos os mapeamentos obrigatórios. 3. O template selecionado ainda é Utility aprovado. 4. O operador tem acesso developer/admin. 5. Os kill switches em nível de config e de workspace permitem a execução. 6. 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. | ## Guias relacionados * [Link de recibo de pagamento via botão de URL](/pt-BR/guides/receipt-link-webhook) * [Recibo em PDF via cabeçalho DOCUMENT](/pt-BR/guides/pdf-receipt-webhook) * [Webhooks de entrada](/pt-BR/api-reference/inbound-webhooks)