Saltar al contenido
Facturador

Webhooks Salientes

Los Webhooks Salientes permiten notificar automáticamente en tiempo real a sistemas externos (n8n, Zapier, Make, ERPs corporativos o bases de datos propias) cuando ocurren eventos en el sistema.

Visión General

Al producirse un evento (como la emisión de un comprobante o la aceptación por SUNAT), el sistema envía una petición POST en formato application/json hacia la URL pública configurada.

Notificaciones en Tiempo Real

Los webhooks se envían de forma asíncrona mediante colas de trabajo, garantizando que la emisión de ventas o compras nunca se ralentice ni se vea interrumpida por la disponibilidad del receptor.

Interfaz de Administración (/configurations/webhooks)

Para gestionar las suscripciones a webhooks, diríjase a Configuraciones Globales → Webhooks.

Lista de Suscripciones

Muestra todas las integraciones configuradas para el tenant actual, con su URL, eventos activos y fallos consecutivos acumulados.

Listado de Webhooks

Nueva Suscripción

Haga clic en "Nuevo" para registrar un nuevo webhook:

  • Nombre: Identificador interno para su referencia.
  • URL: Dirección HTTPS que recibirá los datos (POST).
  • Eventos: Checkboxes de los eventos que dispararán la notificación.

Nuevo Webhook

Secreto del Webhook (Clave HMAC)

Al guardar el webhook, el sistema genera una clave secreta (whsec_...).

Guarde su secreto

Este secreto se utiliza para verificar la firma de seguridad X-Webhook-Signature. Por motivos de seguridad, no se volverá a mostrar completo en la interfaz.

Secreto del Webhook

Editar y Pausar Webhook

  • Editar: Permite cambiar el nombre, URL o eventos suscritos.
  • Activar / Desactivar (Pausa): Desactiva temporalmente el envío sin borrar la suscripción.

Editar Webhook Webhook Inactivo

Eliminar Webhook

Permite remover la suscripción y su historial de entregas de la base de datos.

Eliminar Webhook

Entregas e Historial de Envíos

En la pestaña "Entregas", puede visualizar y auditar todas las peticiones realizadas, ver mensajes de error y solicitar un reintento manual de envío.

Historial de Entregas

Catálogo de Eventos

Evento Descripción
document.created Emisión de un documento de venta (Factura, Boleta, etc.).
document.accepted SUNAT aprobó el documento de venta (CDR disponible).
document.observed SUNAT aceptó el documento pero retornó observaciones.
document.rejected SUNAT rechazó el documento.
document.voided Se aprobó la anulación del documento.
purchase.created Registro de una nueva compra.

Formato del Payload y Encabezados

Cada envío incluye los encabezados:

  • X-Webhook-Event: Nombre del evento.
  • X-Webhook-Id: UUID único del evento (útil para idempotencia).
  • X-Webhook-Signature: Firma criptográfica HMAC SHA-256 del body crudo.

Ejemplo de Payload JSON (document.accepted)

{
  "id": "7b5497c3-17d8-4dd1-9c36-e31f84699b21",
  "event": "document.accepted",
  "api_version": "1.0",
  "created_at": "2026-06-12T13:46:46-05:00",
  "data": {
    "id": 168,
    "external_id": "05cbd9ba-d9ce-4a3a-8c78-7ea0ea8b5ab8",
    "number": "F001-63",
    "filename": "20515809822-01-F001-63",
    "state_type_id": "05",
    "state_type_description": "Aceptado",
    "total": 50,
    "customer": {
      "identity_document_type_id": "6",
      "number": "10414711225",
      "name": "EMPRESA XYZ S.A."
    },
    "links": {
      "xml": "https://tenant.dominio.com/downloads/document/xml/05cbd9ba-d9ce-4a3a-8c78-7ea0ea8b5ab8",
      "pdf": "https://tenant.dominio.com/downloads/document/pdf/05cbd9ba-d9ce-4a3a-8c78-7ea0ea8b5ab8",
      "cdr": "https://tenant.dominio.com/downloads/document/cdr/05cbd9ba-d9ce-4a3a-8c78-7ea0ea8b5ab8"
    }
  }
}

Verificación de Firma HMAC (Seguridad)

En el servidor receptor, se debe comprobar que la firma X-Webhook-Signature coincida con el hash HMAC-SHA256 del payload crudo utilizando el secreto.

$secret = 'whsec_...';
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals(hash_hmac('sha256', $rawBody, $secret), $signature)) {
    http_response_code(401);
    exit('Firma no válida');
}
http_response_code(200);

Reintentos y Tolerancia a Fallos

  • Timeout: 10 segundos por petición.
  • Reintentos Automáticos: En caso de error o código distinto a 2xx, el sistema realiza reintentos automáticos (inmediato, 1m, 10m, 6h, 24h).
  • Auto-desactivación: Si acumula 10 fallos consecutivos, el webhook se desactiva de forma automática hasta que sea reactivado desde la interfaz web.