Webhooks: recibe avisos cuando cambian los datos

En lugar de preguntar a la API una y otra vez «¿hay algo nuevo?», suscríbete a los eventos una sola vez y Roldesk los enviará a tu servidor en cuanto sucedan.

Añade un endpoint

En Ajustes → Desarrollador → Webhooks, añade la URL que debe recibir los eventos y marca los eventos que te interesen (por ejemplo work_order.completed o invoice.created). Mostramos un secreto de firma una sola vez: guárdalo en un lugar seguro. También puedes probar, desactivar o eliminar un endpoint en cualquier momento.

Qué recibes

Cada entrega es un pequeño POST en JSON con cabeceras:

Roldesk-Event:      contract.renewed
Roldesk-Delivery:   <id de entrega>
Roldesk-Signature:  t=<unix_ts>,v1=<hmac-sha256 en hex>

El cuerpo es un evento ligero: usa el id para obtener el objeto completo desde la API REST:

{ "id": "…", "type": "contract.renewed", "created": "…",
  "data": { "object": "contract", "id": "…" } }

Verifica la firma

Confirma siempre que una entrega proviene realmente de Roldesk antes de actuar sobre ella (ejemplo en Node):

import crypto from "crypto";
function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(",").map(x => x.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${p.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(p.v1), Buffer.from(expected));
}

Fiabilidad

Las entregas fallidas se reintentan automáticamente con espera progresiva (hasta 6 intentos). Un endpoint que sigue fallando se desactiva para que no se acumule nada. Los eventos se disparan en cada cambio: desde la app web, la app móvil, la API o acciones automáticas como las renovaciones de contratos.