Webhooks assinados: origem, prazo e replay

Webhooks assinados existem para a automação não obedecer a um corpo que qualquer um posta na URL. A assinatura mostra que quem enviou conhece o segredo. O prazo mostra que a mensagem não é um replay de semana passada. A chave mostra que a segunda entrega do mesmo fato não repete o efeito.
URL secreta não é assinatura. Quem viu o endereço uma vez pode reenviar um JSON antigo. O desenho trata o webhook como uma entrega hostil até que origem, tempo e chave fechem.

O que a assinatura cobre?
Cobre o corpo exato que chegou, e idealmente o instante. Assinar só um campo e deixar o resto solto permite trocar o valor com o selo intacto. A conferência usa o mesmo algoritmo e o mesmo segredo, e rejeita se um byte divergir.
O segredo não mora no código versionado nem na URL. Roda em cofre, com rotação. Dois segredos válidos ao mesmo tempo permitem trocar sem derrubar a entrega que ainda vem com o anterior. Segredo único e eterno é o que vaza no print de um ticket e continua aceito.
Por que o relógio faz parte da prova?
Uma assinatura válida de um mês atrás ainda é válida se não houver prazo. Alguém que capturou o corpo reenvia e a automação cobra de novo, cria de novo, notifica de novo. A janela curta, de poucos minutos, recusa o que chegou tarde demais.
Relógio exige tolerância de alguns segundos entre os dois lados, não de um dia. Tolerância larga demais reabre o replay. A recusa por prazo volta um erro claro, para o emissor reenviar uma mensagem nova, não a mesma hora antiga.
| Checagem | Recusa | Não basta |
|---|---|---|
| Assinatura do corpo | Corpo trocado | URL escondida |
| Prazo curto | Replay antigo | Assinatura sem relógio |
| Chave do fato | Segunda entrega | Aceitar de novo e “ver no log” |
| Segredo rotacionável | Vazamento eterno | Token no repositório |
Como a segunda entrega não repete o efeito?
O emissor tenta de novo quando não recebe resposta. Isso é o normal. A chave é o identificador do fato, pagamento ou pedido, não o ID da tentativa HTTP. A segunda chamada com a mesma chave devolve o estado já aplicado.
Responder erro na segunda vez faz o emissor insistir. Responder sucesso sem dizer que já existia confunde a conciliação. A resposta carrega a chave e o estado. O efeito externo, a cobrança ou a criação, acontece uma vez.
O que fazer com entrega fora de ordem?
Dois eventos do mesmo pedido podem chegar invertidos: cancelado antes de pago, por atraso de rede. Aplicar cegamente o último que chegou deixa o estado errado. A ordem de negócio, quando existe, manda mais do que a ordem de chegada.
Se o evento atrasado é mais antigo do que o estado atual, ele não regride o pedido. Isso se escreve. Sem a regra, o webhook “corrige” um cancelamento de volta para pago porque o pacote antigo chegou depois.
Como provar uma falha sem guardar segredo no log?
O log guarda a chave, o resultado da conferência e o código de recusa. Não guarda o segredo nem o corpo inteiro se ele traz dado pessoal desnecessário. Dá para explicar por que recusou sem reproduzir o cadastro em cada tentativa.
O emissor também precisa de um lugar para ver a falha. Recusar em silêncio faz o outro lado achar que entregou. Um código estável, assinatura inválida, prazo vencido ou chave já aplicada, cabe na resposta e no painel de quem opera os dois lados.
Um exemplo de aviso de pagamento
O provedor avisa que um pagamento foi reconhecido. A automação confere o selo, recusa se o relógio passou da janela e, com a chave do pagamento, vê se aquele aviso já liberou o pedido. A segunda tentativa, comum quando a resposta se perdeu, devolve “já aplicado” e não separa o estoque outra vez.
Um corpo reenviado de uma captura antiga falha no prazo, mesmo com selo verdadeiro da época. Sem o prazo, a assinatura sozinha teria aceitado o replay. Os três controles fecham juntos.
Checklist prático
O webhook está aceitável quando origem, tempo e chave são conferidos antes de qualquer efeito.
- Assinatura do corpo inteiro, não de um campo só
- Segredo fora do código e da URL, com rotação
- Prazo curto e tolerância de relógio pequena
- Chave de negócio distinta do ID da tentativa
- Segunda entrega devolve o estado já aplicado
- Evento atrasado não regride um estado mais novo
- Recusa com código claro para o emissor
- Log sem o segredo e sem o corpo pessoal desnecessário
Erros comuns
Entrega forjada e efeito duplicado nascem quando um dos três controles falta.
- Achar que a URL não publicada é autenticação
- Assinar só o identificador e deixar o valor solto
- Guardar o segredo no repositório
- Aceitar mensagem antiga porque o selo confere
- Tratar cada tentativa HTTP como um fato novo
- Devolver erro genérico na reentrega e provocar outro retry
- Aplicar eventos fora de ordem e regredir o estado
- Gravar o corpo completo, com dado pessoal, em todo log
Onde a entrega entra no fluxo?
Em automações de processos, webhooks assinados são a porta de entrada: sem origem, prazo e chave, o fluxo não deveria agir.