Tempo de leitura estimado : 6 min · Publicado
Escreva o contrato do evento
Documente o produtor, os tipos de eventos esperados, os campos obrigatórios e a operação acionada. Descreva os resultados para criação, alteração e exclusão, quando aplicável. Uma notificação não deve autorizar implicitamente todas as ações possíveis.
Escolha um identificador de rastreamento e uma fonte autorizada para consultar quando incerto. Descreva como são detectadas falhas no produtor ou receptor. A documentação de integração contém regras e proprietários; Os segredos pertencem ao mecanismo seguro do projeto.
No n8n, os URL de webhook de teste e produção têm finalidades diferentes. Escutar um evento de teste não prepara a receção habitual: o URL de produção é registado ao publicar o workflow. Verifique o URL configurado no emissor e consulte as execuções de produção em Executions.
O modo de resposta altera o significado da confirmação. Immediately anuncia o início do workflow, não a atualização da encomenda ou ficha de cliente. Relacione identificador do evento, execução e estado final no destino antes de anunciar sucesso operacional.
Desloque a tabela horizontalmente para ler todas as colunas. Com o teclado, coloque o foco na tabela e utilize as teclas de seta.
| Ponto de controlo | Observação possível | Evidência esperada |
|---|---|---|
| URL de teste | Evento visível durante a escuta de teste | URL e ambiente utilizados no ensaio |
| URL de produção | Workflow publicado e execução registada | Identificador de execução ligado ao evento recebido |
| Resposta Immediately | O workflow foi iniciado | Estado final e operação prevista no serviço de destino |
Verifique antes de acionar uma operação
Validação de assinatura de entrega de documentos do GitHub usando o secreto configurado e a carga útil recebida. Siga o mecanismo documentado do provedor real; Cabeçalhos, algoritmos e formatos não devem ser copiados de outro serviço por analogia.
Verificação de origem separada, validação de esquema e autorização de operação. Teste o conteúdo alterado, um tipo de evento inesperado e um campo ausente. O processamento de negócios deve começar somente após os controles necessários para o caso de uso.
Planeje repetições e interrupções
Definir manipulação idempotente: uma entrega repetida reconhecida não deve criar dois pedidos ou duas notificações finais. Teste a repetição antes, durante e após o processamento e uma interrupção entre as etapas. O mecanismo depende da operação e armazenamento envolvidos.
Verifique as garantias de pedidos e reenvio do provedor, em vez de assumir uma chegada imediata e imediata. Mantenha uma fila de trabalhos exigindo revisão e uma maneira de reconciliá-la com a fonte. Uma resposta técnica positiva deve corresponder a um estado de processamento definido.
Organize o monitoramento e a recuperação
Registre um identificador de evento, um estado e um erro útil ao minimizar os dados. Defina quem monitora as falhas, como os eventos autorizados são repetidos e como as novas tentativas evitam a duplicação do trabalho concluído.
Interrompa o receptor em um ambiente de teste e restaure-o. Verifique o acompanhamento e reconciliar os resultados esperados dos negócios. Entregue um contrato de evento, um lote de teste, um histórico de processamento e um procedimento de recuperação que a equipe pode usar.
Documentação principal: GitHub - validação de entregas de webhook.
Exemplo fictício: DEMO-E41 desencadeia uma única escrita de negócio numa base de dados. O contrato reúne a escrita e a marcação do evento como tratado na mesma transação; uma chave única composta por produtor e identificador controla os tratamentos concorrentes. Teste uma interrupção antes e depois de COMMIT. A recuperação após confirmação encontra o trabalho efetuado em vez de acrescentar outro efeito. Registar «recebido» num diário separado não oferece essa garantia.
No GitHub, uma nova entrega conserva X-GitHub-Delivery: uma nova tentativa não é, só por isso, um novo evento. Verifique separadamente cada outro produtor. DEMO-E42 mostra outro limite: uma chamada a um serviço externo expira sem resposta. Uma transação local não demonstra se o serviço agiu; confronte a referência e as garantias de repetição documentadas antes de repetir a ação.
Desloque a tabela horizontalmente para ler todas as colunas. Com o teclado, coloque o foco na tabela e utilize as teclas de seta.
| Caso testado | Efeito de negócio comprovado | Recuperação esperada |
|---|---|---|
| DEMO-E41 antes de COMMIT, transação anulada | 0 efeitos confirmados | Retomar segundo o registo transacional |
| DEMO-E41 depois de COMMIT | 1 efeito e evento marcado como tratado | Recuperar o resultado já confirmado |
| DEMO-E41 entregue novamente | Continua a existir 1 efeito no total | Reconhecer a chave; não repetir a escrita |
| DEMO-E42: chamada externa sem resposta | Resultado desconhecido: possíveis 0 ou 1 efeito | Confrontar com o serviço; evitar repetição cega |
- GitHub : Webhook Best Practices
GitHub, consultado em 22 de outubro de 2026: identificador conservado na nova entrega. DEMO-E41 e DEMO-E42 são eventos abreviados fictícios.
- PostgreSQL : Transactions
PostgreSQL, consultado em 22 de outubro de 2026: transações na base de dados, sem garantia global para chamadas externas.
Documentos de referência
- Stripe : Webhooks · Fonte consultada
- n8n : Webhook node · Fonte consultada
- GitHub - validação de entregas de webhook
Conteúdo atualizado
Referências documentadas para este tema
| Referência | Valor ou sintaxe | Âmbito |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | JSON padrão não admite comentários nem vírgulas finais; as cadeias usam aspas duplas. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | O desvio explícito relaciona a hora local com UTC; este exemplo não é uma marcação. |
As datas indicam a consulta das fontes. Estes dados não constituem uma auditoria do site nem uma declaração global de conformidade.
