Webhooks salientes

Envía eventos firmados de Nimlio a tu backend cuando cambian pedidos o citas.

Cómo funciona

Registra hasta 5 endpoints HTTPS por negocio en Ajustes -> Webhooks. Cada endpoint se suscribe solo a los tipos de evento que debe recibir.

Catálogo de eventos

order.created

Se creó un pedido de tienda.

order.paid

El proveedor de pago confirmó el pago del pedido.

order.cancelled

El pedido fue cancelado antes de completarse.

order.expired

El pedido o checkout pendiente expiró.

order.refunded

El pago del pedido fue reembolsado.

appointment.requested

Un cliente solicitó una cita.

appointment.confirmed

La cita fue confirmada.

appointment.cancelled

La cita fue cancelada.

Envelope de entrega

Ejemplo de entrega order.paid (abreviado)

{
  "id": "6f1c1d52-3b8e-4c43-9a57-0e2f7d9b1a10",
  "type": "order.paid",
  "createdAt": "2026-07-08T14:30:00Z",
  "businessId": "9f9a...",
  "data": {
    "order-id": "b2d4...",
    "status": "paid",
    "amount-total": 12500000,
    "currency": "COP",
    "created-at": "2026-07-08T14:28:41Z",
    "paid-at": "2026-07-08T14:30:00Z",
    "items": [{ "name": "...", "quantity": 1, "unit-amount": 12500000 }]
  }
}

Cada entrega envía {id, type, createdAt, businessId, data}. El id es un UUID que también viaja en el header X-Nimlio-Delivery. El campo data lo arma el productor y conserva sus claves en kebab-case (por ejemplo order-id, amount-total, starts-at), a diferencia de la Platform API en camelCase. Los eventos de pedidos llevan la misma proyección de estado sin PII de GET /api/v1/orders/{orderId}/status; no existe un endpoint que devuelva el detalle completo del cliente.

Headers de firma

X-Nimlio-EventX-Nimlio-DeliveryX-Nimlio-Signature: t=<unix>,v1=<hex>

Verifica firmas

X-Nimlio-Signature usa t=<unix>,v1=<hex>. v1 es HMAC-SHA256(secret, `${t}.${rawBody}`). Rechaza entregas cuando |now - t| sea mayor a 5 minutos y compara el digest con crypto.timingSafeEqual. El secreto de firma se muestra una sola vez, al crear el endpoint.

Verificación en Node.js

import crypto from "node:crypto";

export function verifyNimlioWebhook({ rawBody, signature, secret, now = Date.now() }) {
  const parts = Object.fromEntries(
    signature.split(",").map((part) => {
      const [key, value] = part.split("=");
      return [key, value];
    }),
  );

  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(now / 1000 - timestamp) > 5 * 60) return false;

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");

  const received = Buffer.from(parts.v1 ?? "", "hex");
  const trusted = Buffer.from(expected, "hex");
  return received.length === trusted.length && crypto.timingSafeEqual(received, trusted);
}

Reintentos y tiempos

Nimlio intenta entregar hasta 7 veces: 1m, 5m, 30m, 2h, 6h y 24h entre reintentos. Después del último intento fallido la entrega queda marcada como muerta, y puedes reenviarla desde el dashboard.

Responde con cualquier estado 2xx. Cada intento tiene un plazo de 10 segundos en el socket (la resolución DNS tiene su propio margen de 3 segundos), así que confirma primero y procesa trabajo costoso de forma asíncrona.