Resposta direta
Um receptor de webhooks precisa autenticar a entrega conforme o contrato do emissor, validar o evento e registrar de forma recuperável o trabalho aceito. Depois, deve reconhecer repetições e aplicar a operação de negócio com idempotência. Receber um POST ou responder com sucesso não prova que o evento é legítimo nem que seu efeito foi concluído.
Webhooks conectam sistemas sem exigir que um deles consulte continuamente o outro. Essa conveniência traz uma responsabilidade: sua URL pública pode receber uma mensagem falsa, atrasada, repetida ou fora da ordem esperada. O projeto precisa explicar como cada entrega atravessa a fronteira de confiança e como a equipe recupera falhas sem executar a mesma ação indevidamente.
- Autenticar a entrega
- Validar e registrar o evento
- Processar com idempotência
- Acompanhar e recuperar
Comece pelo contrato de um emissor específico
Liste quais eventos sua aplicação precisa receber, qual endpoint será chamado e quais respostas o emissor aceita. Confira formato, versão, autenticação, prazo de resposta e comportamento de reenvio. Nomes de cabeçalhos, algoritmos e intervalos não devem ser tratados como um padrão universal entre fornecedores.
Por exemplo, GitHub documenta assinatura em X-Hub-Signature-256 e um identificador de entrega em X-GitHub-Delivery. Stripe tem seu próprio contrato de assinatura e exige atenção ao corpo original. Esses exemplos mostram por que o primeiro trabalho é ler a documentação da integração escolhida, em vez de copiar um receptor genérico e trocar somente a URL.
HTTPS e assinatura cumprem papéis complementares
HTTPS protege a comunicação no transporte. A validação de assinatura prevista pelo emissor ajuda a verificar a origem e a integridade da mensagem na aplicação. Mantenha o segredo no servidor, em uma configuração protegida, fora do repositório, do navegador e de endereços que possam aparecer em logs.
Prefira a biblioteca oficial de verificação quando ela existir e for adequada à versão usada. Se implementar a verificação, siga exatamente o algoritmo, o formato e o método de comparação seguros documentados. Uma comparação improvisada ou uma conversão errada dos dados pode invalidar a proteção mesmo quando o cabeçalho parece correto.
Preserve os dados necessários à verificação
Alguns contratos calculam a assinatura sobre os bytes do corpo recebido. No caso documentado pela Stripe, alterar o corpo antes da verificação pode causar falha. Um parser, uma nova serialização JSON ou um tratamento de caracteres pode transformar uma mensagem semanticamente igual em bytes diferentes.
Defina em que ponto o framework captura o corpo original e em que ponto ocorre a verificação. Depois, valide estrutura e limites da entrada de acordo com o evento esperado. Não registre o segredo ou o payload inteiro para descobrir um problema de assinatura; use uma reprodução controlada com dados de teste e registros minimizados.
Assinatura válida não substitui autorização de negócio
Depois de verificar a entrega, confira tipo, ação e estrutura. Aceite somente o que a integração utiliza e relacione referências à conta, ao projeto ou ao recurso correto no seu sistema. Uma mensagem autêntica pode se referir a algo que não deve produzir aquela ação na aplicação.
Quando o contrato exigir ou o desenho precisar de confirmação atual, consulte o recurso na API autorizada do provedor. Mantenha a distinção entre o estado informado pelo evento e o estado que a regra de negócio precisa confirmar. A aplicação deve decidir quais transições são permitidas, inclusive se uma notificação chega depois de uma mudança mais recente.
Confirme o recebimento depois de uma aceitação recuperável
O endpoint precisa responder dentro das condições do emissor, mas sua resposta deve corresponder ao que realmente foi aceito. Se a aplicação confirma sucesso e cai antes de registrar o trabalho, pode perder a oportunidade de processar uma entrega que o emissor considera concluída. Defina um ponto de persistência e uma forma de retomar o trabalho.
Uma opção de arquitetura é registrar o evento ou uma referência suficiente em armazenamento durável e separar o processamento pesado. Se banco e fila participam, avalie a janela entre gravar e publicar: duas operações em sistemas diferentes não são automaticamente atômicas. Documente como o processo encontra e recupera trabalhos pendentes depois de uma interrupção.
Deduplicação de entrega e idempotência do efeito são distintas
Um identificador de entrega pode ajudar a reconhecer um reenvio da mesma mensagem. Já a operação de negócio pode exigir sua própria chave estável: eventos diferentes podem se referir ao mesmo recurso e ao mesmo efeito. Um campo de identificação sozinho não demonstra que uma tarefa foi executada uma única vez.
Como exemplo didático, um evento inicia a geração de um relatório. O resultado é gravado, mas a confirmação do worker se perde. Na nova tentativa, o sistema deve reconhecer o resultado válido ou retomar com segurança. Se há um efeito externo, a estratégia também depende do contrato desse destino. Uma variável em memória não oferece a mesma recuperação que um estado persistente.
Repetições concorrentes precisam de controle no armazenamento
Duas requisições podem chegar quase juntas. Se ambas consultam primeiro e só depois gravam que o evento foi visto, as duas podem concluir que têm permissão para iniciar a ação. A decisão de reivindicar uma operação precisa de um mecanismo de exclusão apropriado ao banco e ao desenho da aplicação.
Defina estados como recebido, em processamento, concluído e falhou, com transições claras. Diferencie uma operação concluída de uma que foi apenas reivindicada e abandonada por falha. O mecanismo de recuperação deve saber quando pode retomar, sem permitir que dois workers produzam o mesmo efeito simultaneamente. Não transforme um bloqueio sem prazo ou uma chave esquecida em uma tarefa perdida permanentemente.
Planeje reenvio e ordem sem assumir garantias inexistentes
Confira se o provedor reenvia automaticamente, como expõe entregas com falha e o que acontece quando você pede uma nova entrega. Não dependa de uma ordem que não foi garantida. Na Stripe, a documentação orienta tratar duplicações e não presumir ordem de eventos; outros serviços têm condições próprias.
No GitHub, uma nova entrega do mesmo evento conserva o identificador X-GitHub-Delivery conforme sua documentação. Esse detalhe pode ajudar a testar a deduplicação naquele contrato, mas não deve ser extrapolado para qualquer emissor. Guarde as referências relevantes e defina um procedimento de recuperação que consulte o estado já registrado antes de repetir uma ação.
Observe o percurso do evento com dados minimizados
Registre horário, emissor, tipo, identificador de entrega quando disponível, referência interna, resultado da validação e estado do trabalho. Correlacione esses dados com status HTTP e duração. Isso permite distinguir rejeição de assinatura, entrada inválida, indisponibilidade e falha depois do recebimento.
Limite retenção e acesso aos registros. Payloads podem conter dados de clientes ou informações que não precisam permanecer em um log. Um alerta útil aponta falhas persistentes, trabalhos antigos ou um aumento inesperado de repetição, com uma ação conhecida para a equipe. Apenas contar respostas 200 não revela se as operações terminaram corretamente.
Teste interrupções que comprovem o comportamento esperado
Use um ambiente autorizado e eventos de teste, sem disparar efeitos reais indevidos. Compare os resultados com o contrato documentado do emissor e com a regra da aplicação. O ensaio deve testar a fronteira de autenticação, a repetição e a recuperação, e não apenas mostrar uma resposta de sucesso.
Registre o que deve acontecer em cada caso e as limitações do teste. Uma implementação confiável permite explicar por que uma entrega foi aceita ou rejeitada e como uma operação pendente será tratada. Isso produz evidências melhores que afirmar que o sistema nunca duplica eventos.
| Caso de teste | Resultado esperado | O que conferir |
|---|---|---|
| Assinatura inválida | Rejeição conforme o contrato | Nenhum efeito de negócio |
| Mesmo evento reenviado | Reconhecimento da repetição | Estado e efeito já registrado |
| Duas entregas concorrentes | Reivindicação controlada | Proteção no armazenamento |
| Falha após aceitação | Trabalho recuperável | Registro persistente e retomada |
| Evento fora de ordem | Transição autorizada | Regra e estado atual do recurso |
Como a WordPane ajuda a operar o receptor
Na WordPane, os recursos de logs e métricas ajudam a relacionar falhas do endpoint à aplicação e ao uso do servidor. As ferramentas de publicação por Git e os ambientes de teste compatíveis ajudam a organizar versões e validar alterações antes de atingir a integração pública. Confirme runtime, processos e requisitos do projeto no ambiente escolhido.
Quando houver processamento em segundo plano, confira os comandos, o gerenciamento de processos e as dependências realmente disponíveis no escopo. A estratégia de backups com destino externo precisa incluir os dados e configurações necessários à recuperação. A infraestrutura não implementa automaticamente assinatura, deduplicação ou regras de negócio: essas proteções pertencem ao código da integração. Leve fluxo, volume de eventos, picos e recuperação ao briefing para avaliar capacidade e responsabilidades.
Planeje a infraestrutura das suas integrações
Descreva emissores, volume de eventos, runtime e recuperação para avaliar o ambiente do seu receptor e dos processos associados.
Avaliar minha integração com a WordPaneConsultar a documentação do painel
