Notificaciones y aprobaciones

Webhooks salientes y un bot de Telegram para eventos sealed/failed/promoted/needs_approval, mas /approve y /reject desde el chat.

Objetivo#

Recibir un aviso de estado — nunca un diff, nunca contenido de archivos — en el momento en que un worker sella o un worktree se promueve, y opcionalmente aprobar o rechazar una sesion desde Telegram en vez de la CLI. Dos canales independientes, ambos opt-in: webhooks salientes genericos (cualquier URL — Slack, Discord, n8n, Zapier, tu propio receptor) y un bot de Telegram por long-polling.

Pasos#

Agrega uno o mas webhooks en orch.yaml:
```
notify:
  webhooks:
    - url: "https://example.com/orch-hook"
      events: [sealed, failed, promoted, needs_approval] # vacio = todos
      secret_env: ORCH_WEBHOOK_SECRET
```
Cada entrega es un POST con un body JSON — event, workspace, project, session, agent, status, exit, verdict, guard_lines, usage.in/out, log_path, ts — y, cuando secret_env nombra una variable de entorno definida, un header X-Orch-Signature: el HMAC-SHA256 en hex del body crudo bajo ese secreto. Verificalo antes de confiar en el payload.

Envia un evento sintetico para comprobar el cableado:

orch notify test [--event sealed|failed|promoted|needs_approval]

Agrega un bot de Telegram (habla con @BotFather por un token; escribele al bot una vez para que getUpdates pueda ver el id de tu chat):
```
notify:
  telegram:
    bot_token_env: ORCH_TELEGRAM_TOKEN
    chat_allowlist: [123456789]
    events: [sealed, failed, promoted, needs_approval]
```
orch daemon arranca el worker de long-poll automaticamente cuando notify.telegram.bot_token_env esta definido. Para correrlo por su cuenta:
```
orch notify telegram run
```
Desde un chat en la allowlist: /status, /approve <session>, /reject <session> (marca failed + limpia el worktree). Un mensaje de cualquier otro chat id recibe orch: unauthorized chat y no ejecuta nada mas.
Exigir aprobacion antes de que un sellado limpio sea elegible para mezclar:
```
promote:
  require_approval: true
```
Una sesion que sella ok dispara needs_approval en vez de quedar lista para mezclar; /approve <session> (o orch worktree promote <session>) sigue siendo lo que hace el merge de verdad.

n8n / Zapier#

Ambas plataformas hablan HTTP plano — apunta su nodo trigger "catch webhook" a tu URL receptora y pon esa URL en notify.webhooks[].url. No hace falta un nodo propio de Orchemax: el nodo Webhook de n8n y el "Catch Hook" de Zapier parsean el body JSON directamente; agrega un paso Code/Filter sobre event si solo quieres reaccionar a needs_approval, y verifica X-Orch-Signature en ese paso si el webhook es alcanzable desde fuera de tu red.

Lo que nunca sale de la maquina#

Los payloads llevan solo estado y resumen — lineas de veredicto del guard, conteo de archivos, uso de tokens — nunca un diff ni contenido de archivo. El codigo se queda local; solo el evento de arriba cruza la red, y solo hacia las URLs/chats que configuraste.