Assinatura de webhook para agentes de IA: valide antes de agir
Veja como validar a assinatura de webhook antes que um agente de IA aja, com corpo bruto, janela de tempo, deduplicação e limites de aprovação para escritas.

Para validar a assinatura de um webhook antes que um agente de IA aja, recalcule a assinatura sobre o corpo bruto exato da requisição usando o segredo compartilhado com aquele remetente, compare os dois valores em tempo constante e rejeite qualquer evento cujo carimbo de tempo esteja fora da janela documentada pelo remetente. Somente eventos que passem por essas checagens devem chegar ao agente, e o agente deve tratar o conteúdo como dado a classificar, e não como uma nova instrução.
Principais pontos
- Valide a assinatura no corpo bruto da requisição antes de qualquer interpretação, reescrita ou repasse ao agente.
- Use um segredo separado para cada remetente e cada ambiente, e compare assinaturas em tempo constante.
- Rejeite carimbos de tempo antigos e identificadores de evento repetidos, para que um evento capturado não possa ser reenviado.
- Liste em uma allowlist os tipos de evento que o agente pode ler, e mantenha toda escrita atrás de um limite de aprovação.
- Registre cada evento rejeitado com origem, horário e motivo, para que as falhas fiquem visíveis para o responsável.
Por que um webhook sem assinatura abre caminho para instruções falsas
Um webhook é uma requisição HTTP que outro sistema envia ao seu endpoint quando algo acontece, como um pagamento recusado, um formulário enviado ou um chamado que muda de status. O endpoint é apenas uma URL, e URLs vazam. Elas aparecem em logs, arquivos de configuração, documentos compartilhados e painéis de fornecedores. Se o agente tratar qualquer coisa que chegue àquele endereço como evento verdadeiro, quem encontrar o endereço pode fazer o agente acreditar que um pedido foi cancelado ou que um fornecedor trocou os dados bancários.
A checagem de assinatura fecha esse caminho. O remetente calcula um hash com chave sobre o evento, usando um segredo que só ele e o seu endpoint conhecem, e envia o resultado em um cabeçalho. O seu endpoint recalcula o hash e aceita o evento somente se os dois valores coincidirem. Uma assinatura válida mostra que a requisição veio de quem tem o segredo e não foi alterada no caminho. Ela não prova que o conteúdo é correto ou seguro, e essa diferença define o restante do desenho.
Como validar a assinatura de um webhook antes que o agente aja
A ordem das etapas importa tanto quanto a criptografia. Execute-as na borda do seu sistema, antes que qualquer coisa chegue à janela de contexto do agente ou às suas ferramentas:
- Leia o corpo bruto da requisição como bytes, antes de qualquer parser de JSON ou middleware do framework reescrevê-lo.
- Extraia a assinatura e, quando o remetente fornecer, o carimbo de tempo dos cabeçalhos, seguindo o formato descrito na documentação do remetente.
- Calcule a assinatura esperada com o segredo atribuído àquele remetente e àquele ambiente específico.
- Compare os dois valores com uma função de comparação em tempo constante, nunca com uma simples igualdade de strings.
- Rejeite a requisição se o carimbo de tempo estiver fora da janela de tolerância descrita pelo remetente, o que limita a repetição de eventos antigos.
- Verifique o identificador do evento contra os identificadores processados recentemente e pare se o evento já tiver sido tratado.
- Interprete o JSON somente depois que as checagens passarem e confirme que o tipo do evento está na lista que este agente pode tratar.
- Entregue ao agente um evento normalizado, com origem, horário de recebimento e tipo do evento anexados, e deixe as verificações normais de permissão governarem qualquer ação que venha depois.
A maioria dessas etapas exige pouco código. As falhas comuns surgem quando alguém pula essas etapas em uma rota de teste conveniente, ou quando reserializa o JSON já interpretado antes de checar a assinatura, o que altera espaços e a ordem das chaves e faz eventos válidos falharem. A equipe então desativa a checagem para que o fluxo funcione, e a porta continua aberta. Outras lacunas frequentes são usar o mesmo segredo em homologação e produção, aceitar requisições sem assinatura em uma rota que ainda está acessível, registrar cabeçalhos completos que expõem o segredo e confiar em um campo do payload, como um rótulo de origem, que o remetente controla.
A Stripe documenta como assina os eventos de webhook e como um servidor receptor deve validá-los, incluindo o papel do carimbo de tempo no conteúdo assinado. Leia a descrição do próprio fornecedor para cada sistema que você conectar, porque nomes de cabeçalho, codificações e comportamento de tolerância variam. Um trecho de código copiado de um fórum não substitui a documentação do fornecedor. Se você ainda está escolhendo entre push e pull para um fluxo, webhooks ou consultas periódicas em fluxos de IA apresenta as trocas antes de você construir a entrada.
A assinatura comprova o remetente, não o conteúdo
Um evento corretamente assinado ainda pode trazer texto que tenta conduzir o agente. Uma observação de cliente, a descrição de um chamado ou um campo de formulário em texto livre pode conter uma frase escrita como instrução. As orientações da OWASP sobre prevenção de injeção de prompt tratam conteúdo externo como entrada não confiável, inclusive quando ele chega por um canal que você controla. A resposta prática é arquitetural. Coloque os campos do payload em uma seção de dados claramente marcada na entrada do agente. Instrua o agente de que esses campos são registros a classificar, não comandos. Mantenha as saídas dele como propostas. Exija um aprovador nomeado para qualquer escrita. Mantenha as permissões das ferramentas restritas, para que uma etapa de raciocínio manipulada não alcance uma ferramenta de que a tarefa não precisava.
Cenário ilustrativo: uma loja recebe um evento corretamente assinado informando a recusa de um pagamento com cartão. A observação do cliente no payload pede ao agente que cancele o pedido e emita o reembolso. O agente classifica o evento como falha de pagamento, redige uma resposta para o líder de suporte e registra a observação como pedido do cliente. Nenhum reembolso é feito até que um aprovador nomeado confirme no canal de aprovação. A checagem de assinatura confirmou de onde o evento veio, e o desenho de permissões decidiu o que o agente podia fazer com as palavras contidas nele. O mesmo padrão vale para permissões de leitura, rascunho e envio, em que redigir é permitido, mas enviar é uma concessão separada.
Quais eventos podem chegar a um agente, e em que forma
A validação é um portão, e esse portão deve ser combinado com uma decisão para cada tipo de evento. Um guia simples para uma equipe de operações fica assim:
- Eventos de status, como uma atualização de entrega, podem chegar ao agente como contexto somente leitura para resumos e consultas.
- Eventos de entrada, como um novo lead recebido, podem chegar ao agente com permissão para classificar e redigir uma resposta.
- Eventos que disparariam uma escrita, como a criação de uma fatura ou um reembolso, devem produzir uma proposta que uma pessoa aprova antes que qualquer ferramenta altere um registro.
- Eventos de uma origem sem assinatura verificável não devem chegar ao agente de forma alguma, e devem ir para uma fila de revisão sob responsabilidade de uma pessoa.
- Tipos de evento que ninguém revisou devem ser descartados e registrados até que alguém os inclua na allowlist com um responsável nomeado.
Um evento válido também pode chegar mais de uma vez, porque remetentes reenviam a entrega quando não recebem resposta em tempo hábil. Mantenha a checagem de duplicidade ligada ao caminho de escrita, não apenas à etapa de entrada. As orientações de idempotência para ações de agentes explicam como fazer com que um evento repetido produza um único efeito.
Como a Be Human trata a entrada de webhooks em um projeto gerenciado
Em um projeto com a Be Human, a entrada de webhooks faz parte do desenho da integração, e não é um detalhe posterior. A equipe define quais eventos o agente pode ler, configura um segredo separado e uma etapa de validação para cada remetente e cada ambiente, estabelece as regras de deduplicação e de allowlist, e documenta quais ações continuam atrás de um limite de aprovação. A operação gerenciada então revisa os logs de eventos rejeitados nas revisões de permissão, trata as falhas como incidentes, rotaciona os segredos em um cronograma acordado com o cliente e reabre o desenho quando um fornecedor muda o formato de assinatura ou o esquema do evento. O objetivo é um caminho de entrada que o dono do negócio possa inspecionar, e não um caminho que dependa de um desenvolvedor lembrar como ele funciona.
Testar e operar a checagem depois do lançamento
Antes de entrar em produção, envie um evento de exemplo corretamente assinado e, em seguida, o mesmo corpo com um caractere alterado, um evento com carimbo de tempo antigo, um identificador de evento repetido e um tipo de evento que não esteja na allowlist. Cada caso deve produzir o resultado que você planejou, e cada um deve deixar um registro de log com origem, horário e motivo, sem o segredo em si. Repita o mesmo teste após cada mudança do fornecedor, porque formatos de assinatura e esquemas de payload mudam com o tempo. Depois, escolha o primeiro evento que vale entregar a um agente, definindo um tipo de evento, um responsável nomeado e uma verificação observável que mostre se o resultado foi correto. Se você não tem certeza de qual deve ser esse evento, o diagnóstico gratuito de IA da Be Human pode ajudar a identificar essa primeira tarefa.
Perguntas frequentes
Ainda preciso de checagem de assinatura se a URL do meu webhook é difícil de adivinhar? Um endereço escondido não é um método de autenticação, porque endereços aparecem em logs, arquivos de configuração e documentos compartilhados. A checagem de assinatura é simples de implementar e comprova que o remetente tem o segredo. Mantenha a URL difícil de adivinhar, mas não dependa só disso para decidir em que o agente deve confiar.
Qual método de assinatura devo esperar de um fornecedor? Muitos fornecedores usam um hash com chave, como HMAC com SHA-256, mas o nome do cabeçalho, o conteúdo assinado e as regras de tolerância mudam de um fornecedor para outro. Alguns publicam chaves públicas para verificação assimétrica. Siga a documentação do fornecedor para cada origem e teste com um evento de exemplo antes de conectá-la a um agente.
O que o agente deve fazer quando a validação falha? O endpoint deve rejeitar o evento sem repassar nenhuma parte dele ao agente, devolver o status que o protocolo espera, quando isso for possível, e registrar origem, horário e motivo sem armazenar segredos. Falhas repetidas vindas de uma mesma origem devem alertar a pessoa responsável pela integração. O agente nunca deve tentar interpretar um evento rejeitado, porque o objetivo da checagem é impedir que conteúdo não verificado entre no contexto dele.
A checagem de assinatura substitui as aprovações para escritas? Não. A checagem de assinatura informa quem enviou o evento, enquanto as aprovações decidem se o agente pode agir sobre o que o evento diz. Um remetente verificado ainda pode enviar dados desatualizados ou uma instrução enganosa, e um evento assinado pode conter um texto que nunca deveria virar um reembolso ou uma troca de dados bancários sem que uma pessoa confirme. Mantenha os dois controles ativos.
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.


