Webhooks

Los webhooks te permiten reaccionar en tiempo real a lo que pasa en tu cuenta de Recibix: cada vez que ocurre un evento (por ejemplo, se emite una factura), Recibix envía una petición POST a la URL que configures.

Los webhooks están disponibles en los planes Pro y Empresarial, y durante la prueba gratis. La URL debe ser HTTPS y pública (no se permiten direcciones internas o privadas).

Crear un webhook

En Configuración → Webhooks crea un endpoint con:

• URL — tu endpoint HTTPS que recibirá los eventos.
• Secret — una clave (mínimo 8 caracteres) que usarás para verificar la firma. Guárdala en tu servidor.
• Eventos — a cuáles te quieres suscribir.

Puedes usar Enviar test para recibir un evento de prueba y validar tu integración. Puedes tener hasta 10 webhooks activos, y cada uno guarda un historial de sus últimas entregas para depurar.

Eventos disponibles

Evento	Cuándo ocurre	data
factura.emitida	Se emite una factura	facturaId, numeroFactura, clienteId, total
factura.anulada	Se anula una factura	facturaId, numeroFactura
factura.pagada	Una factura llega a saldo 0	facturaId, numeroFactura, clienteId, total
pago.registrado	Se registra un pago	pagoId, facturaId, monto, metodoPago
compra.pagada	Se marca una compra como pagada	compraId, numeroFactura, total

Formato del payload

El cuerpo es JSON con esta estructura:

{
  "evento": "factura.emitida",
  "empresaId": "a1b2c3d4-...",
  "timestamp": "2026-06-28T15:04:05.000Z",
  "data": {
    "facturaId": "380f3805-...",
    "numeroFactura": "001-001-01-00000028",
    "clienteId": "9c9bcb58-...",
    "total": 1150.0
  }
}

Cabeceras

Cada petición incluye:

• X-Recibix-Event — el nombre del evento (ej. factura.emitida).
• X-Recibix-Signature — la firma en formato sha256=<hex>.
• Content-Type: application/json.

Verificar la firma

La firma es un HMAC SHA-256 del cuerpo crudo de la petición, usando tu secret. Verifícala siempre antes de confiar en el evento. Usa el raw body exacto: si lo vuelves a serializar, la firma no coincidirá.

import crypto from "crypto";
import express from "express";

const app = express();

// Importante: necesitas el cuerpo crudo para verificar la firma
app.post(
  "/webhooks/recibix",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const secret = process.env.RECIBIX_WEBHOOK_SECRET;
    const firma = req.header("X-Recibix-Signature") || "";
    const esperado =
      "sha256=" +
      crypto.createHmac("sha256", secret).update(req.body).digest("hex");

    const ok =
      firma.length === esperado.length &&
      crypto.timingSafeEqual(Buffer.from(firma), Buffer.from(esperado));

    if (!ok) return res.status(401).send("Firma inválida");

    const evento = JSON.parse(req.body.toString());
    // procesa evento.evento y evento.data ...
    console.log("Evento recibido:", evento.evento);

    res.status(200).send("ok");
  },
);

app.listen(3000);

Reintentos

Si tu endpoint no responde con un código 2xx, Recibix reintenta la entrega automáticamente más tarde. Por eso:

• Responde rápido con 2xx y procesa en segundo plano si la tarea es pesada.
• Diseña tu handler para que sea idempotente (un mismo evento podría llegar más de una vez).

Buenas prácticas

• Verifica siempre la firma antes de actuar.
• Guarda el secret como variable de entorno, nunca en el código.
• Usa HTTPS en tu endpoint.
• Registra los eventos recibidos para depurar.

Para la configuración a nivel de usuario, ver también Email, actividad y herramientas.