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
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.
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
sobrees tu clave de idempotencia. - Contestá 2xx aunque el hecho ya lo tengas: así el reintento no te vuelve a llegar.