Notificaciones y aprobaciones

Webhooks salientes, bot local de Telegram (avisos suaves en Professional) y Assist HITL SaaS (Team) con /approve y /deny — nunca diffs ni contenido de archivos.

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. Tres canales independientes, todos opt-in:

Webhooks salientes genericos (cualquier URL — Slack, Discord, n8n, Zapier, tu propio receptor) desde el taller local orch.
Un bot de Telegram local por long-polling (orch notify telegram) para los mismos eventos del taller y /approve / /reject sobre sesiones selladas.
Assist HITL de Orchemax SaaS (Team en adelante): vincula un chat en /app/assist; /approve / /deny / /reject en el bot de Orchemax escriben los mismos avisos que el boton Assist de la consola. Professional mantiene Telegram avisos suaves (telegram_notify) sin Assist de org.

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.

Assist HITL SaaS (Team)#

Cuando el taller esta vinculado a una cuenta Orchemax en Team o Enterprise:

Abre orchemax.com/app/assist y vincula el chat_id de Telegram del bot que usa tu tenant.
Desde ese chat envia /approve <asunto>, /deny <asunto> o /reject <asunto> (/reject es el alias de deny). El servidor registra un aviso HITL en orch_notices y renueva el lease de entitlements — el mismo camino que los botones aprobar/negar de Assist en la consola.
Free, Starter y Professional reciben el gate de plan (telegram_hitl_requires_team); sube de plan en Billing. Professional sigue incluyendo Telegram avisos suaves (telegram_notify) para alertas / /answer en el bot local.

Este canal solo lleva metadatos (asunto approve/deny + tenant). No reemplaza orch notify telegram local para sellar/promover en tu maquina — usa ambos si quieres pings del taller y Assist SaaS.

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.

Bandeja del sistema#

Para un icono persistente que abre orch ui y muestra los mismos toasts de escritorio, mira Presencia en la bandeja.