Webhooks — Entrada Universal de Eventos | Easy Understand Hermes Agent

Webhooks — Entrada Universal de Eventos

Imagine só: um desenvolvedor abre um pull request no GitHub e, em segundos, seu agente de IA já revisou o código e postou um comentário. Ou um pagamento falha no Stripe e seu agente notifica automaticamente seu time no Telegram. Essa é a mágica dos webhooks — eles permitem que serviços externos batam na porta do seu agente e digam: “Ei, algo acabou de acontecer, resolve isso pra gente.”

O Que São Webhooks?

Webhooks são como uma campainha para suas aplicações. Em vez de ficar verificando constantemente se algo mudou (polling), você simplesmente espera a campainha tocar. Quando o GitHub, GitLab, JIRA, Stripe ou qualquer outro serviço envia uma requisição HTTP POST para o seu endpoint de webhook, seu agente Hermes acorda, processa o evento e age.

A melhor parte? Seu agente pode responder de várias formas — postando comentários em PRs, enviando mensagens para o Telegram ou Discord, ou simplesmente registrando o resultado para revisão posterior.

Início Rápido

Começar é surpreendentemente simples:

Ative o adaptador de webhook via hermes gateway setup ou variáveis de ambiente
Defina rotas em config.yaml ou crie-as dinamicamente com hermes webhook subscribe
Aponte seu serviço para http://seu-servidor:8644/webhooks/<nome-da-rota>

Pronto. Seu agente agora está de plantão.

Configurando o Gateway

Você tem duas formas de ativar webhooks, escolha a que preferir.

Opção 1: O Assistente de Configuração

hermes gateway setup

Siga as instruções para ativar webhooks, escolher uma porta e definir um segredo HMAC global. O assistente cuida de toda a configuração chata pra você.

Opção 2: Variáveis de Ambiente

Adicione estas linhas ao ~/.hermes/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # padrão
WEBHOOK_SECRET=seu-segredo-global

Com o gateway rodando, verifique se está vivo:

curl http://localhost:8644/health

Você deve ver:

{"status": "ok", "platform": "webhook"}

Configurando Rotas

Rotas são o coração do tratamento de webhooks. Cada rota diz ao seu agente como lidar com eventos de uma fonte específica. Pense nelas como instruções personalizadas para diferentes tipos de visitantes.

Veja o que você pode configurar por rota:

Propriedade	O que faz
`events`	Quais tipos de evento aceitar (ex.: `["pull_request"]`). Deixe vazio para aceitar tudo.
`secret`	Segredo HMAC para validação de assinatura. Use `"INSECURE_NO_AUTH"` apenas para testes.
`profile`	Qual perfil pode executar esta rota (útil com multiplexação).
`prompt`	Template de string usando notação de ponto como `{pull_request.title}`. Omita para despejar o payload JSON completo.
`filters`	Condições declarativas para ignorar payloads indesejados antes do agente rodar.
`script`	Um script de filtro/transformação que pode modificar o payload antes da renderização do template.
`skills`	Quais skills carregar para esta execução do agente.
`toolsets`	Quais ferramentas o agente pode usar (substitui o toolset padrão de webhook).
`deliver`	Para onde enviar a resposta: `github_comment`, `telegram`, `discord`, `slack`, `log` e outros.
`deliver_extra`	Detalhes adicionais de entrega, como nome do repositório ou ID do chat.
`deliver_only`	Pule o agente completamente e entregue o prompt renderizado diretamente. Custo zero de LLM!

Um Exemplo do Mundo Real

Vamos ver uma configuração prática. Aqui está uma rota que revisa pull requests:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "segredo-global-fallback"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "segredo-webhook-github"
          prompt: |
            Revise este pull request:
            Repositório: {repository.full_name}
            PR #{number}: {pull_request.title}
            Autor: {pull_request.user.login}
            URL: {pull_request.html_url}
            URL do diff: {pull_request.diff_url}
            Ação: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

E aqui está uma rota que envia uma notificação no Telegram apenas quando alguém faz push para a branch main:

        deploy-notify:
          events: ["push"]
          secret: "segredo-deploy"
          prompt: "Novo push em {repository.full_name} branch {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

Filtragem Inteligente

O recurso de filters é especialmente útil. Provedores costumam enviar uma enxurrada de eventos, mas você só se importa com alguns. Filtros permitem ignorar o ruído antes mesmo do seu agente acordar. Payloads que não correspondem recebem uma resposta educada {"status":"ignored","reason":"filter"} com HTTP 200 — sem computação desperdiçada, sem chamadas de LLM desnecessárias.

Modo de Entrega Direta

Aqui vai um truque esperto: defina deliver_only: true e seu agente nem chega a rodar. O template do prompt renderizado se torna a mensagem literal que é entregue. Isso significa entrega em menos de um segundo com custo zero de LLM. Perfeito para notificações simples que não precisam de raciocínio de IA.

Nota de Segurança

Lembre-se: autenticado não significa confiável. Campos de payload de webhooks são dados não confiáveis. Sempre valide e sanitize qualquer coisa que você usar em prompts ou templates. Seu agente deve tratar conteúdo de webhook como entrada de usuário — com ceticismo saudável.

Conclusão

Webhooks transformam seu agente Hermes em um assistente responsivo que reage ao mundo em tempo real. Seja automatizando revisões de código, enviando notificações de deploy ou construindo fluxos de trabalho complexos orientados a eventos, o adaptador de webhook torna tudo isso possível com apenas algumas linhas de YAML.