YoRobot.

Esta página en Markdown: /docs/webhooks.md

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

EventoCuándo
tarea.creadauna tarea entró a la cola
tarea.terminadauna tarea terminó, con su veredicto
tarea.necesita_firmauna tarea espera la aprobación de una persona
tarea.firmadaalguien aprobó
tarea.rechazadaalguien rechazó el trabajo
discrepancia.detectadael agente dijo que estaba y la verificación dijo que no
consumo.tope_80el gasto del mes pasó el 80 % del tope
tarea.frenadauna tarea lleva más de una hora frenada y nadie la mueve
promocion.pendienteuna versión espera la segunda firma para salir a producción
conexion.pedidaalguien pidió una credencial que falta para una conexión en un ambiente
consola.escaladaalguien escaló un registro desde una consola, con motivo
rutina.absorbiendouna automatización lleva varios disparos seguidos absorbidos detrás de una misma tarea abierta
consumo.tope_100el gasto del mes llegó al tope: la cola frenó hasta que se suba o empiece el mes
plan.cambiadoel plan de la organización cambió (con sus límites)
aprobacion.pendienteuna 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.mensajeentró un mensaje nuevo en una conversación de un canal (chat, WhatsApp, mensajería)
briefing.listoel 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.borradorel 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 sobre es tu clave de idempotencia.
  • Contestá 2xx aunque el hecho ya lo tengas: así el reintento no te vuelve a llegar.