Webhooks - avisos automáticos a tus sistemas

Un webhook es un aviso que FacturaMax le manda a tu sistema (tu ERP, tu tienda, una planilla conectada) cada vez que pasa algo con tus documentos: se creó una factura, SIFEN la aprobó, la rechazó… Así tu sistema se entera solo, sin tener que preguntar a cada rato. Esta guía es un poco más técnica: si no tenés un sistema propio, probablemente no la necesites.

app.facturamax.app/bm-admin/webhooks

Los eventos

Crear un endpoint

app.facturamax.app/bm-admin/webhooks

Qué recibe tu sistema

Cada aviso es un POST con un cuerpo JSON y estos encabezados:

Ejemplo de un de.approved:

{
"event": "de.approved",
"timestamp": "2026-10-16T10:32:05-03:00",
"data": {
  "id": 1520,
  "cdc": "01800123456001001000014322026101611234567890",
  "tipo_de": 1,
  "estado": "APPROVED",
  "numero": "001-001-0000143",
  "fecha_emision": "2026-10-16",
  "receptor_ruc": "80099999-1",
  "receptor_nombre": "Cliente Ejemplo S.A.",
  "moneda": "PYG",
  "total": "1765000.0000",
  "sifen_codigo_respuesta": "0260",
  "sifen_mensaje": "Aprobado",
  "sifen_protocolo": "123456",
  "sent_at": "2026-10-16T10:31:58-03:00",
  "approved_at": "2026-10-16T10:32:05-03:00"
}
}

Los eventos evento.accepted y evento.rejected traen en data el evento_id, el de_id y el cdc del documento (vacíos si el evento no es sobre un documento, como una inutilización), el tipo_evento, el motivo, el estado, el sifen_codigo y el sifen_mensaje.

Verificar la firma

Para estar seguro de que el aviso viene de FacturaMax, calculá un HMAC-SHA256 del cuerpo tal cual lo recibiste (los bytes crudos, sin volver a armar el JSON) usando tu secret como clave. El resultado, en hexadecimal, tiene que ser igual al encabezado X-FacturaMax-Signature.

const crypto = require('crypto');

app.post('/sifen/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const recibida = req.get('X-FacturaMax-Signature') || '';
const esperada = crypto
  .createHmac('sha256', process.env.FACTURAMAX_WEBHOOK_SECRET)
  .update(req.body) // el cuerpo crudo
  .digest('hex');

const ok = recibida.length === esperada.length &&
  crypto.timingSafeEqual(Buffer.from(recibida), Buffer.from(esperada));
if (!ok) return res.status(401).end();

const aviso = JSON.parse(req.body);
// ... procesá aviso.event y aviso.data
res.status(200).end();
});

$cuerpo   = file_get_contents('php://input');
$recibida = $_SERVER['HTTP_X_FACTURAMAX_SIGNATURE'] ?? '';
$esperada = hash_hmac('sha256', $cuerpo, getenv('FACTURAMAX_WEBHOOK_SECRET'));

if (! hash_equals($esperada, $recibida)) {
  http_response_code(401);
  exit;
}

$aviso = json_decode($cuerpo, true);
// ... procesá $aviso['event'] y $aviso['data']
http_response_code(200);

Respondé rápido y con 2xx

• Tu sistema tiene 10 segundos para contestar. Contestá con un código 2xx (por ejemplo 200) apenas recibas el aviso, y hacé el trabajo pesado después.
• Cualquier respuesta fuera de 2xx cuenta como falla.

Reintentos y desactivación automática

En la tarjeta de cada webhook aparece una etiqueta amarilla con la cantidad de fallos cuando los hay. Para volver a activarlo, arreglá tu endpoint y tocá la etiqueta INACTIVO de la tarjeta: pasa a ACTIVO y el contador de fallas se pone en 0.

Probar y revisar las entregas

Hacé clic en la tarjeta de un webhook para abrir su detalle. Ahí tenés:

• Probar ahora: manda un aviso de prueba con el evento webhook.test y el mensaje «This is a test webhook delivery from FacturaMax.». Sirve para verificar la URL y la firma.
• Actualizar entregas, Editar (URL, descripción y eventos), Rotar secret y Eliminar.
• Eventos suscriptos: los que elegiste.
• Entregas recientes (se actualiza cada 10 segundos): cada aviso enviado con el Evento, el Status (por ejemplo 200 OK, 500 ERR, PENDING o FAILED), el número de Intento, cuánto Tiempo tardó tu sistema en contestar y hace cuánto se envió.