workflows

Webhook recebido: valide a origem antes da ação

Confira a assinatura conforme o provedor, consulte o estado atual e só então decida o efeito de negócio.

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.

Fontes