Webhook de entrada por agente

Camada funcional

Um endereço próprio do agente para sistemas de terceiros chamarem. Diferente dos gatilhos de aplicativo (que dependem de um serviço com integração pronta), aqui qualquer sistema que saiba fazer uma chamada HTTP pode acionar o agente.

Autenticação: duas formas

Duas formas de provar quem está chamando: por assinatura do corpo da chamada, ou por segredo simples. A assinatura é a forma preferida, porque prova que o corpo não foi alterado no caminho — não apenas que quem chamou conhece um segredo compartilhado. O segredo simples existe pelo pragmatismo de integrar sistemas que não sabem assinar.

Corpo livre

Aceita qualquer JSON. Isso é o que torna o endpoint universal — e também o que exige a peça seguinte.

Extração de campo

Há um recurso de leitura por caminho no corpo, o que permite ao cadastro do webhook apontar onde está a informação relevante dentro de um JSON arbitrário, em vez de exigir que o remetente se adapte ao nosso formato.

O objetivo declarado é a montagem da entrada do agente a partir do corpo recebido — isto é, converter um payload de terceiro numa mensagem que faz sentido para o agente.

Limite de taxa

Há verificação explícita de limite antes de processar. Endpoint público sem limite é convite a abuso: cada chamada aceita inicia trabalho de agente, que custa sandbox e modelo.

Duração

Teto de duração estendido, coerente com o fato de que a chamada pode iniciar um run.

Onde fazer isso

Pela tela do agente dá para criar, listar, editar e remover os endereços de webhook do agente. Cada endereço criado recebe um segredo próprio, usado para assinar ou autenticar as chamadas que chegam por ele.

Comparação com os outros caminhos de entrada

A escolha entre o primeiro e o segundo é de granularidade: o webhook é por agente e por endereço, com segredo próprio; a chave de API é da organização, com escopos e seleção de agentes.