Torne os webhooks e integrações de sites confiáveis

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.

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.