Verificação de assinatura de webhook: barre eventos forjados e repetidos
Valide a assinatura sobre o corpo bruto, confira o horário e guarde os IDs de evento para o agente agir só em eventos autênticos, novos e inéditos.

Para verificar a assinatura de um webhook usado por um agente de IA, recalcule um HMAC sobre o corpo bruto exato da requisição, usando o segredo que o remetente lhe entregou, compare o resultado em tempo constante com o cabeçalho de assinatura e confirme que o carimbo de data é recente. Em seguida, guarde o ID do evento fornecido pelo provedor, para que uma entrega repetida ou reenviada não acione o agente uma segunda vez. Só eventos verificados e novos devem chegar ao modelo, e o agente deve agir sobre eles apenas pelas ferramentas que o papel dele permite.
Principais pontos
- Verifique a assinatura sobre o corpo bruto da requisição, antes de qualquer interpretação, reformatação ou middleware do framework tocar nele.
- Compare assinaturas em tempo constante e rejeite qualquer evento cujo carimbo de data esteja fora da janela de tolerância.
- Deduplique pelo ID do evento do provedor, porque entregas legítimas repetidas parecem replays para um handler ingênuo.
- Trate todo campo do conteúdo como texto não confiável e deixe o agente agir somente por ferramentas com escopo definido e aprovado.
- Registre cada rejeição com um motivo, pois as rejeições revelam configurações erradas, segredos expirados e tentativas de sondagem.
Por que um agente exige mais verificações que um handler simples
Um handler de webhook que grava uma linha em uma tabela falha de forma limitada. Com um agente, o risco é outro. Ele lê o evento, raciocina sobre ele e pode chamar ferramentas que enviam uma mensagem, rascunham uma fatura ou alteram um registro. Um evento forjado vira, então, um pedido para agir, e por isso o caminho de entrada precisa responder a três perguntas separadas antes de o agente ver qualquer coisa.
A primeira pergunta é autenticidade: quem enviou conhecia o segredo compartilhado? A segunda é frescor: a requisição foi enviada há pouco tempo, ou alguém está reenviando uma captura antiga? A terceira é unicidade: esse evento já foi processado? Uma assinatura válida responde apenas à primeira. Mesmo um evento perfeitamente assinado pode conter um pedido que o agente não deveria atender, então a autorização das ações seguintes continua pertencendo à camada de ferramentas. O conteúdo sobre permissões mínimas para agentes de IA aprofunda essa segunda fronteira.
Passo a passo: verifique a assinatura antes de o agente ver o evento
A ordem das operações importa. Cada etapa deve terminar antes da próxima começar, e qualquer falha deve interromper o processamento com um motivo registrado. Uma sequência prática fica assim:
- Configure a rota que recebe os eventos para expor o corpo bruto. Desative qualquer middleware global de JSON que interprete e serialize de novo o corpo nesse caminho, porque uma mudança de espaços ou de ordem das chaves quebra o HMAC.
- Leia o cabeçalho de assinatura e o carimbo de data exatamente como o provedor documenta. Alguns provedores assinam o carimbo junto com o corpo, outros assinam só o corpo. Siga o esquema do provedor, e não um esquema que você lembra de outra integração.
- Carregue o segredo compartilhado deste endpoint a partir de um cofre de segredos. Mantenha-o fora de prompts, da memória do agente, de arquivos de configuração que as pessoas copiam e de logs da aplicação.
- Calcule o HMAC com o algoritmo especificado pelo provedor e compare com o valor recebido usando uma função de comparação em tempo constante, e não uma simples igualdade de strings.
- Confira o carimbo de data contra a janela de tolerância. Rejeite eventos antigos demais e também carimbos com data absurdamente no futuro, porque problemas de relógio e adulteração produzem ambos.
- Só depois que todas as verificações passarem, interprete o JSON e valide-o contra o esquema daquele tipo de evento. Campos desconhecidos ou malformados devem parar o fluxo aqui, e não seguir adiante.
- Confirme a entrega com uma resposta de sucesso e então coloque o evento verificado na fila de processamento do agente. Fazer o raciocínio mais lento depois da confirmação mantém o endpoint responsivo e evita timeouts que disparam reentregas.
A documentação de webhooks da Stripe mostra uma implementação concreta de entregas assinadas com carimbo de data, e serve de referência útil mesmo que seu provedor seja outro.
Como rejeitar eventos repetidos
Um replay acontece quando alguém captura uma requisição assinada válida e a envia de novo. A checagem do carimbo de data reduz a janela em que isso é possível, mas não a fecha. Dentro dessa janela, a mesma requisição válida continuará passando no teste de assinatura, por isso você precisa de um segundo controle.
Esse controle é um armazenamento de IDs de evento. Cada evento do provedor traz um identificador único. Antes de o agente processar o evento, insira esse identificador em uma tabela que imponha unicidade. Se a inserção falhar porque o identificador já existe, confirme a entrega, não execute nenhuma ação e registre o evento como duplicado. O registro da inserção e o estado do processamento devem ser gravados juntos, para que uma queda entre a verificação e a ação não deixe um evento marcado como tratado quando não foi, ou o contrário.
A retenção importa. Mantenha os identificadores pelo menos pelo tempo da janela de tolerância somado ao período de reentrega documentado pelo provedor. Confira por quanto tempo o provedor continua tentando reenviar uma entrega com falha, porque um registro que expira cedo demais reabre a porta para uma segunda ação. A mesma ideia aparece no conteúdo sobre ações idempotentes em agentes de IA, que aplica o princípio às escritas que o agente faz, e não apenas aos eventos de entrada.
Guia de decisão para eventos rejeitados ou suspeitos
O handler deve escolher um desfecho para cada entrega. Um guia simples mantém esses desfechos consistentes entre integrações:
- Cabeçalho de assinatura ausente ou malformado: rejeite, registre o endpoint e o motivo, e conte o evento para um limite de alerta.
- Assinatura não confere: rejeite sem processar, registre o motivo e avise a pessoa responsável pela integração.
- Carimbo de data fora da janela de tolerância: rejeite, registre como possível replay e revise a origem se o padrão se repetir.
- ID do evento já registrado: confirme sem ação e registre como duplicado.
- Assinatura válida, evento novo, validação de esquema falha: guarde o conteúdo em uma área restrita de revisão, não deixe o agente agir e avise um responsável.
- Assinatura válida, evento novo, esquema aprovado: entregue ao agente os campos interpretados e os metadados de verificação, e deixe as permissões das ferramentas decidirem o que ele pode fazer em seguida.
Repare que só o último desfecho chega ao raciocínio do agente. Todos os outros caminhos terminam antes de o modelo entrar em cena, o que mantém o contexto do agente livre de dados que falharam na verificação.
A verificação decide se o evento é real e novo. As permissões decidem se o agente pode agir sobre ele.
Trate o conteúdo como dado, não como instrução
Um webhook autêntico ainda pode carregar texto hostil ou descuidado. Um cliente pode escrever uma mensagem em um campo de formulário, um chamado de suporte pode incluir uma instrução colada, ou o nome de um documento pode conter uma frase dirigida ao modelo. A injeção de prompt é um dos riscos centrais listados nas recomendações de segurança para aplicações com modelos de linguagem, justamente por esse motivo. A defesa é estrutural: as instruções operacionais do agente vêm do papel configurado, o evento chega como dado claramente rotulado, e toda ação relevante passa por uma ferramenta que aplica as próprias permissões, independentemente do que o modelo concluiu.
Cenário ilustrativo: um provedor de pagamentos envia um evento assinado informando que uma fatura foi paga. As verificações de assinatura e de carimbo passam, e o ID do evento é novo. O agente atualiza a própria lista de tarefas e rascunha uma nota de conciliação para a equipe financeira. O lançamento do pagamento no sistema contábil aguarda um aprovador nomeado, porque o papel do agente permite rascunhos, mas não lançamentos. Se a descrição do evento contivesse uma instrução para lançar mesmo assim, a ferramenta ainda recusaria, porque a permissão está na ferramenta, e não no texto.
Para aprovações, um fluxo de aprovação no Slack para ações de agentes é uma forma comum de colocar uma pessoa identificada entre uma escrita rascunhada e o sistema em produção.
Como a Be Human trata a entrada de eventos em um projeto gerenciado
A Be Human trata o caminho de entrada como parte da infraestrutura do agente, e não como um script lateral. Em um projeto gerenciado, o segredo de verificação fica em um cofre controlado, com acesso restrito à integração. As checagens de assinatura, de carimbo de data e de deduplicação rodam antes de o agente receber qualquer evento, e as ferramentas do agente carregam os limites de aprovação definidos para o seu papel. O monitoramento acompanha o volume de rejeições e padrões incomuns, revisões de permissão confirmam quais ferramentas o agente ainda alcança, e a resposta a incidentes segue um caminho escrito caso um segredo seja exposto ou um padrão de replay apareça. Cada agente mantém uma identidade nomeada, o que torna suas ações rastreáveis nos sistemas que ele toca.
Teste o caminho de entrada antes de o agente entrar no ar
Os testes devem cobrir os caminhos de falha, porque é ali que a primeira versão costuma quebrar. Antes de conectar um provedor real, verifique o seguinte:
- Envie um evento corretamente assinado e confirme que ele chega ao agente uma única vez.
- Envie o mesmo evento de novo e confirme que a segunda entrega é confirmada e não processada.
- Altere um único byte do corpo e confirme que a verificação de assinatura rejeita a requisição.
- Envie um evento com carimbo antigo e confirme que ele é rejeitado com motivo de carimbo.
- Remova o cabeçalho de assinatura e confirme que a rejeição é registrada sem armazenar o corpo completo.
- Troque o segredo em um ambiente de teste e confirme que o endpoint aceita o novo valor e recusa o antigo.
Depois do lançamento, revise o registro de rejeições em uma agenda regular, troque os segredos conforme um plano documentado e sempre que pessoas com acesso mudarem de função, e execute avaliações periódicas de como o agente lida com eventos incomuns, mas válidos. Mantenha os logs enxutos: o endpoint, o ID do evento, o resultado e o código do motivo geralmente bastam, e dados pessoais em cargas completas só devem ser guardados quando houver uma finalidade clara.
Se você não tem certeza de qual evento de entrada é o primeiro que vale entregar a um agente, faça o diagnóstico gratuito de IA da Be Human para identificar a primeira tarefa que merece um agente.
Perguntas frequentes
Preciso de verificação de assinatura se meu provedor é conhecido? Sim. Um provedor de peso protege o lado dele do canal, mas o seu endpoint é um sistema separado, com exposição própria, e uma rota sem assinatura ou sem checagem pode ser chamada por qualquer pessoa que descubra o endereço. A verificação de assinatura confirma que a requisição veio de alguém que tem o segredo, que é a condição mínima para confiar nela.
A checagem de carimbo de data basta para impedir replays? Ela reduz a janela, mas não a fecha, porque uma requisição capturada continua válida pelo tempo da janela de tolerância. Combine a checagem de carimbo com um armazenamento de IDs de evento já processados, assim uma segunda entrega do mesmo evento é reconhecida e ignorada mesmo dentro da janela.
O agente deve receber o corpo bruto do webhook ou uma cópia interpretada? O agente deve receber uma cópia interpretada que já passou pela validação de esquema e contém apenas os campos que a tarefa exige. Guarde o corpo bruto em um armazenamento restrito para auditoria ou revisão de disputas, se o seu processo exigir, e evite colocá-lo em prompts, onde dados pessoais desnecessários ou texto hostil poderiam chegar ao modelo.
E se minha plataforma já verifica os webhooks para mim? Confirme exatamente qual camada faz a checagem, se ela cobre carimbos de data e deduplicação e o que faz com eventos que falham. Mesmo quando a plataforma verifica assinaturas, o agente ainda precisa da própria validação de esquema, do tratamento idempotente e dos limites de aprovação, porque esses protegem contra erros e conteúdo injetado que uma verificação de assinatura não detecta.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


