Um endereço de webhook público pode receber chamadas de qualquer origem. Antes de atualizar um pedido ou enviar uma confirmação, a equipe precisa saber se a notificação corresponde ao contrato do provedor usado naquela integração.
Resposta curta
Valide a autenticação documentada para o produto e o tipo de evento recebidos antes de executar a ação. Se a verificação falhar ou não puder ser feita, interrompa o efeito de negócio e investigue. Se a ação depender do estado ou da liquidação, consulte o objeto na API autorizada; em todos os casos, verifique se aquela ação já ocorreu. Uma assinatura válida não confirma pagamento nem impede reentrega.
Os quatro portões de decisão
| Portão | Pergunta | Decisão se a evidência faltar |
|---|---|---|
| Contrato | Este evento e produto têm método de autenticação documentado? | Não adivinhe o algoritmo; consulte a documentação específica. |
| Origem e integridade | Cabeçalho, segredo e conteúdo recebido passam na verificação exigida? | Não processe o efeito; preserve apenas diagnóstico sem segredo. |
| Estado atual | A API autorizada confirma o objeto e a transição esperada? | Mantenha o pedido pendente para conciliação. |
| Efeito anterior | A ação de negócio para esse ID já foi aplicada? | Reconcilie antes de repetir. |
Esta matriz é uma síntese editorial da Pulse. Os portões são sequenciais: aprovar o primeiro não substitui os outros. Preserve o corpo original da requisição quando o provedor exigir verificação sobre os bytes recebidos; uma transformação anterior pode invalidar a assinatura. Nunca registre o segredo ou a carga completa com dados de cliente em logs de diagnóstico.
Confirme o contrato do seu provedor
No Brasil, o Mercado Pago documenta o cabeçalho x-signature e a validação de notificações para integrações aplicáveis. A própria documentação aponta exceções para determinadas notificações de QR Code: não presuma que todo evento usa a mesma assinatura. O PagBank tem procedimento próprio de autenticação. A Stripe também exige corpo original e segredo do endpoint na verificação. Um exemplo de outro provedor não é implementação intercambiável.
Antes de ativar, anote produto, tipo de notificação, versão da documentação, cabeçalhos esperados, segredo associado ao endpoint e como tratar uma falha. Faça uma verificação controlada com os recursos de teste oficiais do provedor, dados fictícios e autorização da operação. Esses são passos propostos, não resultados de testes da Pulse.
Depois de autenticar, decida o efeito
Uma notificação pode chegar mais de uma vez ou depois de uma mudança de estado. Consulte o pagamento ou pedido na fonte autorizada e use um identificador estável para decidir se a ação ainda é devida. O guia de webhook duplicado detalha essa segunda defesa. Para conferir venda e recebimento, use a conciliação de recebimentos.
Se o provedor não oferecer uma forma verificável de autenticar aquele evento, não chame a notificação de confiável por vir de uma URL conhecida. Documente a limitação e procure uma confirmação pela API ou suporte oficial antes de automatizar o efeito.
Fontes e limites
Os procedimentos dependem do produto e da versão do provedor. Consulte Mercado Pago, PagBank e, quando aplicável, Stripe antes de implementar. A matriz organiza decisões; não substitui a especificação técnica nem garante ausência de fraude ou duplicatas.