# Webhooks

Un webhook es una URL tuya a la que YoRobot le manda un POST cuando pasa algo. Se configura en Ajustes → Accesos (o se lista con `GET /api/v1/webhooks`), eligiendo qué eventos querés.

## Eventos

| Evento | Cuándo |
|---|---|
| `tarea.creada` | una tarea entró a la cola |
| `tarea.terminada` | una tarea terminó, con su veredicto |
| `tarea.necesita_firma` | una tarea espera la aprobación de una persona |
| `tarea.firmada` | alguien aprobó |
| `tarea.rechazada` | alguien rechazó el trabajo |
| `discrepancia.detectada` | el agente dijo que estaba y la verificación dijo que no |
| `consumo.tope_80` | el gasto del mes pasó el 80 % del tope |
| `tarea.frenada` | una tarea lleva más de una hora frenada y nadie la mueve |
| `promocion.pendiente` | una versión espera la segunda firma para salir a producción |
| `conexion.pedida` | alguien pidió una credencial que falta para una conexión en un ambiente |
| `consola.escalada` | alguien escaló un registro desde una consola, con motivo |
| `rutina.absorbiendo` | una automatización lleva varios disparos seguidos absorbidos detrás de una misma tarea abierta |
| `consumo.tope_100` | el gasto del mes llegó al tope: la cola frenó hasta que se suba o empiece el mes |
| `plan.cambiado` | el plan de la organización cambió (con sus límites) |
| `aprobacion.pendiente` | una tarea entró a la cola de aprobaciones (verificada, en revisión o esperando a una persona), con el enlace para aprobarla en el portal |
| `conversacion.mensaje` | entró un mensaje nuevo en una conversación de un canal (chat, WhatsApp, mensajería) |
| `briefing.listo` | el briefing del día de una persona quedó listo y verificado, y sale por su canal (el cuerpo trae ids y el link, no el contenido) |
| `briefing.borrador` | el briefing de una persona quedó en borrador: la verificación no lo aprobó o el copiloto no entregó un briefing válido |

Los nombres son contratos: no cambian aunque cambie el vocabulario del portal.

## El pedido

```http
POST /tu-endpoint
content-type: application/json
x-yorobot-evento: tarea.terminada
x-yorobot-sobre: tarea.terminada:<id de la tarea>:<sello>
x-yorobot-signature: t=1722258000,v1=<hmac hex>
```

El cuerpo es JSON con `evento`, `sobre`, `cuando` (ISO) y los datos del hecho. **`sobre` identifica el hecho, no el intento**: si lo recibís dos veces, es el mismo hecho reintentado; procesalo una sola vez guardando el `sobre`.

Las cabeceras viejas `x-estancia-*` viajan al lado con el mismo valor.

## Comprobar la firma

`v1` es HMAC-SHA256, con el secreto del webhook, de la cadena `${t}.${cuerpo crudo}`. Rechazá si `t` está a más de 5 minutos de tu reloj.

```ts
import { createHmac, timingSafeEqual } from 'node:crypto';

export function avisoValido(secreto: string, cuerpoCrudo: string, cabecera: string): boolean {
  const partes = new Map(cabecera.split(',').map((p) => p.trim().split('=') as [string, string]));
  const t = Number(partes.get('t'));
  const v1 = partes.get('v1') ?? '';
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const esperada = createHmac('sha256', secreto).update(`${t}.${cuerpoCrudo}`).digest('hex');
  return esperada.length === v1.length && timingSafeEqual(Buffer.from(esperada), Buffer.from(v1));
}
```

Usá el cuerpo **crudo** (los bytes que llegaron), no el JSON re-serializado.

## Reglas de entrega

- Timeout de 10 segundos: acusá recibo con un 2xx y procesá después.
- No se siguen redirecciones: un 30x cuenta como falla.
- Lo que falla se reintenta desde la cola hasta 5 veces con espera creciente (unos 8 minutos en total); el `sobre` es tu clave de idempotencia.
- Contestá 2xx aunque el hecho ya lo tengas: así el reintento no te vuelve a llegar.
