Webhooks de saída
Receba eventos assinados no seu servidor, com retries e histórico.
Configurar o destino
Em Integrações do site, proprietários e administradores podem adicionar até cinco destinos. Informe nome, URL HTTPS pública na porta 443, ambiente e tipos de evento. URL não pode conter usuário, senha, parâmetros ou fragmento. O segredo de assinatura é mostrado somente na criação ou rotação; guarde-o server-side. Não coloque o segredo no script, na URL ou no navegador do seu cliente.
Eventos e ambiente
event.recorded representa um evento personalizado aceito: ID, nome, caminho e horário. payment.recorded representa pagamento confirmado: ID Pulsant, provedor, ambiente, moeda, valor inteiro em unidades mínimas, estado e horário; feeMinor é opcional e aparece só quando o gateway informa a taxa. payment.fee_reported informa uma taxa que chegou depois do registro do pagamento, com ID do pagamento, provedor, moeda, taxa e horário de observação. payment.adjusted informa ID do ajuste/pagamento, tipo, moeda, valor inteiro, ambiente e horário. O envelope tem id, type, version: 1, occurredAt, workspaceId, siteId e data. Os destinos recebem somente eventos e pagamentos reais. Não enviamos pageviews, identidades, e-mail, propriedades de evento ou payload completo do gateway. Não há envio retroativo nem garantia de ordem.
Validar antes de processar
O contrato segue Standard Webhooks. Cabeçalhos: webhook-id, webhook-timestamp (Unix em segundos) e webhook-signature. Remova o prefixo whsec_ do segredo e decodifique o restante como base64. Calcule HMAC-SHA256 sobre id + ponto + timestamp + ponto + os bytes brutos do corpo; a assinatura é v1, seguida da assinatura em base64. Compare em tempo constante, verifique tolerância de horário (por exemplo cinco minutos), valide o schema e deduplique pelo webhook-id antes de aplicar efeitos. O ID e corpo permanecem iguais nos retries; timestamp e assinatura são gerados novamente. Não verifique a assinatura de um JSON reserializado.
Confirmar e repetir
Responda 2xx após registrar duravelmente o recebimento no seu servidor. Timeout de dez segundos, falhas de rede, 408, 425, 429 e 5xx podem ser repetidos. Outras respostas 4xx e redirecionamentos encerram a tentativa automática. São até oito tentativas, com esperas aproximadas de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h, limitadas à janela de 72 horas. Uma falha após seu servidor aceitar o evento pode causar entrega repetida; não há promessa de exatamente uma entrega.
Histórico e reprocessamento
O histórico tem paginação, estado, HTTP e erro seguro; Ver tentativas mostra cada início/resultado sem conteúdo da resposta. Reprocessamento manual exige destino ativo, falha, conteúdo ainda disponível, janela de 72 horas e confirmação do ID. Preserva ID/corpo e concede até oito novas tentativas, com teto técnico total de 40. Repetições não criam pagamento, ajuste ou débito de evento novamente. A indisponibilidade Redis não elimina o registro PostgreSQL/outbox.
Pausar, rotacionar e revogar
Pausar deixa de selecionar o destino para novos eventos e cancela entregas ainda não iniciadas; retomar recebe os próximos eventos, sem replay das canceladas. Uma requisição já em trânsito pode terminar. Rotação invalida o segredo anterior imediatamente e as próximas tentativas usam o novo: atualize seu receptor. Revogação remove o segredo local e impede novas entregas, preservando o histórico. Perda de permissão da pessoa que configurou o destino também cancela entregas futuras.
Proteções e retenção
O servidor revalida permissão por workspace/site, conta e destino antes de cada envio. DNS é consultado novamente; qualquer endereço privado, local, reservado ou de transição é recusado. O endereço permitido é fixado na conexão HTTPS, preservando SNI e verificação do certificado. Não seguimos redirecionamentos nem capturamos conteúdo de respostas. Payloads expiram após 30 dias e entregas pendentes após 72 horas. A configuração representa uma delegação explícita de dados ao seu servidor; não configure destinos de terceiros sem autorização.
Evidências
Os testes unitários cobrem assinatura e transporte DNS/TLS com dependências controladas. O teste integrado usa PostgreSQL/BullMQ/ClickHouse reais e receptor HTTP restrito a loopback, com transporte de teste explicitamente substituído. Isso não comprova entrega TLS em um destino externo de produção. Nenhum destinatário externo foi contatado para receber notificações nos testes.