Listener de Webhooks do Microsoft Graph

Pense assim: em vez de o seu telefone ficar checando a geladeira pra ver se o leite acabou, a geladeira te manda uma mensagem no momento em que o leite termina. É exatamente isso que um listener de webhook faz — ele espera por um sinal e reage automaticamente.

---

O Que Isso Faz, Na Prática?

O Microsoft Graph Webhook Listener é um recurso do Hermes Agent que permite que o Microsoft 365 (M365) avise o Hermes quando algo acontece — como uma reunião do Teams terminando, uma nova mensagem de chat chegando ou um evento de calendário sendo atualizado.

Não é um chatbot com quem você conversa. É mais como um assistente silencioso que fica ouvindo as “notificações de alteração” do Microsoft Graph e, então, aciona um pipeline para fazer algo útil — como buscar a transcrição de uma reunião e publicar um resumo de volta no Teams.

---

O Que Você Precisa Antes de Começar

Você vai precisar de três coisas:

1. Credenciais de app do Microsoft Graph — registre um app no portal Azure da Microsoft.
2. Uma URL HTTPS pública — o Microsoft Graph não chama localhost. Um dev tunnel funciona para testes; um domínio real é o ideal para produção.
3. Um segredo forte — este é o seu valor clientState, usado para verificar se as notificações são realmente da Microsoft.

Gere um segredo com:

openssl rand -hex 32

Coloque-o no ~/.hermes/.env assim:

MSGRAPH_WEBHOOK_CLIENT_STATE=seu-segredo-gerado-aqui

---

Configuração Rápida

A maneira mais simples de ativar o listener é com um arquivo de configuração mínimo (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "substitua-por-um-segredo-forte"
      accepted_resources:
        - "communications/onlineMeetings"

Ou use variáveis de ambiente no ~/.hermes/.env (elas são mescladas automaticamente na inicialização):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=seu-segredo-gerado-aqui
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Nota: O host de bind é lido apenas de extra.host no arquivo de configuração — não existe a variável de ambiente MSGRAPH_WEBHOOK_HOST para sobrescrever isso.

---

Iniciando o Listener

Execute este comando para iniciar o gateway:

hermes gateway run

Depois de iniciado, o listener expõe estes endpoints:

• POST /msgraph/webhook — recebe notificações de alteração do Microsoft Graph
• GET /msgraph/webhook?validationToken=... — lida com o handshake de validação da assinatura
• GET /health — um probe de prontidão com contadores para notificações aceitas/duplicadas

---

Tornando-o Público

Para que o Microsoft Graph alcance o seu listener, você precisa expô-lo publicamente. Use um proxy reverso, dev tunnel ou ingress. Sua URL de notificação para as assinaturas do Graph será:

https://ops.example.com/msgraph/webhook

---

Tabela de Configuração Rápida

Todas as configurações ficam em platforms.msgraph_webhook.extra:

Configuração	Padrão	O Que Faz
host	não definido (todas as interfaces)	Endereço de bind. Use 127.0.0.1 para dev tunnels.
port	8646	Porta para escutar.
webhook_path	/msgraph/webhook	Caminho onde o Graph faz POST.
health_path	/health	Endpoint de prontidão.
client_state	—	Seu segredo compartilhado, comparado com segurança.
accepted_resources	[] (aceita tudo)	Lista de permissões dos caminhos de recursos do Graph. Use * para curingas.

---

Resumo e Dica Prática

O Microsoft Graph Webhook Listener é a sua ponte entre os eventos do M365 e as ações do Hermes. Não é complicado — é apenas um listener esperando por um sinal e, então, acionando um fluxo de trabalho.

Dica prática: Comece com accepted_resources limitado a um único recurso (como communications/onlineMeetings) para manter as coisas simples. Quando você vir as notificações fluindo, expanda a lista. E sempre use um client_state gerado corretamente — é o seu aperto de mão de segurança com a Microsoft.

---