Webhooks assinados: origem, prazo e replay

Envelope lacrado entrando num encaixe e uma cópia atrasada sendo devolvida

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.

Selo de um envelope conferido ao lado de um relógio antes da porta abrir
O selo e o relógio decidem se a entrega entra.

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.

ChecagemRecusaNão basta
Assinatura do corpoCorpo trocadoURL escondida
Prazo curtoReplay antigoAssinatura sem relógio
Chave do fatoSegunda entregaAceitar de novo e “ver no log”
Segredo rotacionávelVazamento eternoToken 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.

Perguntas frequentes

▸HTTPS sozinho não basta?

HTTPS protege o caminho. Não prova que o corpo veio do provedor certo, nem que não é um replay. A assinatura e o prazo é que fecham isso. Certificado válido com corpo forjado continua sendo um POST qualquer.

▸Qual prazo usar?

Minutos, não dias, com tolerância para o relógio dos dois lados. O emissor que falhou gera uma mensagem nova. Alongar a janela para “não perder entrega” reabre o replay que o prazo existe para impedir.

▸Como rotacionar o segredo sem queda?

Aceitando o segredo atual e o anterior por um período curto, e só então retirando o antigo. Troca instantânea perde a entrega que já saiu assinada com o segredo anterior. A rotação tem data de fim.

▸O emissor não assina. O que fazer?

Tratar como integração frágil: rede restrita, lista de origem se ela for estável, chave de negócio e conferência do fato na API do emissor antes do efeito. Confiar no JSON porque “é o nosso fornecedor” não segura um replay.

▸Preciso guardar o corpo para auditoria?

Guarde a chave, o tipo do evento e o resultado. O detalhe sensível fica no sistema dono do fato, não numa cópia em cada tentativa. Auditoria de automação explica o efeito. Não precisa de um segundo cadastro.

▸Como testar o replay?

Reenvie o mesmo corpo assinado duas vezes e confira um efeito só. Reenvie um corpo com relógio velho e confira a recusa. Troque um byte e confira que o selo falha. Teste de uma entrega feliz não cobre esses três.