Webhooks

Un webhook es un aviso automático que ISPManager envía a otro sistema cuando ocurre algo. Con esta función, cada vez que se registra un pago, ISPManager le avisa al instante a la dirección de un sistema externo —por ejemplo, el software de contabilidad o el CRM de la agencia— para que ese sistema se entere del pago sin que nadie tenga que digitarlo de nuevo.

Cada aviso se envía firmado, de modo que el sistema que lo recibe puede comprobar que viene realmente de ISPManager y que nadie lo alteró por el camino.

Quién puede configurarlos

Esta página solo aparece para los usuarios que tienen el permiso Gestionar Webhooks. Si no la ve en el menú, pídale a su administrador que le asigne ese permiso.

Cada usuario administra solo los webhooks de sus propias agencias. Al crear o editar uno, en la lista de agencias únicamente aparecen las agencias a las que pertenece.

Para abrir el módulo, en el menú lateral entre a Comunicaciones y luego a Webhooks.

La lista de webhooks

La página principal muestra todos los webhooks configurados, uno por fila.

Cada fila indica:

Columna	Qué muestra
ISP y Agencia	A quién pertenece el webhook.
URL	La dirección del sistema externo al que se envía el aviso.
Eventos	Qué hechos disparan el envío. Hoy el único evento disponible es Pago registrado; en la lista se muestra con su clave payment.created.
Estado	ACTIVO si está enviando avisos, INACTIVO si está pausado.
Acciones	El botón Editar para abrir y modificar el webhook.

Para crear uno nuevo, use el botón NUEVO WEBHOOK que está arriba de la tabla.

Crear un webhook

El formulario está dividido en tres secciones: a dónde se envía, qué lo dispara y si está activo.

Campo	Descripción
Agencia	La agencia cuyos pagos se van a notificar. Obligatorio.
URL de destino	La dirección a la que se envía el aviso. Debe empezar por https:// y usar un nombre de dominio público; no se aceptan direcciones IP ni direcciones internas. Obligatorio.
Descripción	Un texto libre para recordar a quién pertenece el webhook (por ejemplo, "software contable"). Opcional.
Eventos	Los hechos que disparan el aviso. Marque al menos uno. Hoy solo existe Pago registrado, que viene seleccionado.
Estado	Si Activo está marcado, el webhook envía avisos. Si lo desmarca, queda pausado y no se envía nada.

Para crear el webhook:

1. Elija la Agencia.
2. Escriba la URL de destino del sistema que va a recibir los avisos.
3. Opcionalmente, escriba una Descripción.
4. Deje marcado el evento Pago registrado.
5. Deje Activo marcado si quiere que empiece a enviar de inmediato.
6. Presione Crear webhook.

Deje el evento marcado

El evento Pago registrado ya viene seleccionado. Debe quedar al menos un evento marcado: si lo desmarca, el sistema no le dejará guardar el webhook.

El secreto se crea solo

Al crear el webhook, ISPManager genera automáticamente un secreto de firma. No se escribe a mano: aparece después, en la pantalla de edición, para que lo copie y lo entregue al sistema que recibe los avisos.

El secreto de firma

Cuando abre un webhook con Editar, a la derecha aparece el panel Secreto de firma. Ese secreto es la clave con la que ISPManager firma cada aviso, y es lo que permite al sistema receptor comprobar que el mensaje es auténtico.

• Use el botón de copiar para llevar el secreto al sistema del cliente.
• Compártalo solo con ese sistema. Cualquiera que tenga el secreto podría imitar los avisos de ISPManager.
• El botón Regenerar secreto crea uno nuevo y anula el anterior.

Regenerar el secreto rompe la conexión hasta actualizarlo

Al regenerar el secreto, el sistema del cliente dejará de aceptar los avisos hasta que usted le entregue el nuevo valor y lo actualice allí. Regénerelo solo cuando sea necesario (por ejemplo, si el secreto se filtró) y coordine el cambio con la persona que administra el sistema receptor.

Cuándo se envía el aviso

El aviso Pago registrado se envía cada vez que se registra un pago real del cliente, sin importar por dónde entró:

• Pagos tomados en caja por un usuario.
• Pagos por la pasarela Wompi.
• Pagos importados desde el recaudo de Bancolombia.
• Recargas de saldo de los servicios prepago tomadas en caja.

Para que el aviso salga, la agencia debe tener un webhook activo suscrito al evento. Si no hay ninguno, no se envía nada.

No se envía aviso en estos casos, porque no son dinero nuevo que entra:

• Aplicaciones de saldo a favor del cliente y los cobros automáticos diarios de los servicios prepago (se descuentan del saldo, no son dinero nuevo).
• Reversos de pago por nota crédito y ajustes internos.
• Movimientos con valor cero o negativo, incluidos los pagos que solo registran una retención.
• Anular o restaurar un pago tampoco envía nada: no existe un aviso de anulación.

El envío ocurre en segundo plano: registrar el pago no se demora ni falla aunque el sistema externo esté lento o caído. Si el sistema receptor no responde, o responde con un error de servidor (5xx), 408 o 429, ISPManager reintenta hasta 5 veces espaciando cada intento (aproximadamente 30 s, 2, 5 y 15 minutos). Cualquier otro error (400, 401, 403, 404…) se considera definitivo y no se reintenta. Si mientras tanto el webhook se desactiva o cambia de agencia, los reintentos pendientes se descartan.

No hay registro de entregas en pantalla

El panel no muestra si cada aviso llegó o falló. Si el sistema externo no recibe un pago, confirme con quien lo administra y revise que la URL, el secreto y el estado del webhook sean correctos.

Qué contiene el aviso

Esta sección es para la persona que programa el sistema que recibe los avisos.

Cada aviso es una solicitud POST con un cuerpo en formato JSON. Esta es su forma para el evento de pago:

{
  "event": "payment.created",
  "payment": {
    "id": 481023,
    "amount": 50000.00,
    "paid_at": "2026-06-17T10:32:45-05:00",
    "payment_method": "EFECTIVO",
    "reference": "REC-000123",
    "type": "SERVICIOS",
    "description": "Pago factura junio",
    "invoice_ids": [739812]
  },
  "service": { "id": 78061 },
  "subscriber": { "id": 73236, "name": "EMPRESA DEMO S.A.S." },
  "agency": { "id": 86, "name": "BOLIVAR" }
}

Dato	Significado
event	Siempre payment.created para este aviso.
payment.id	Identificador del pago en ISPManager.
payment.amount	Valor del pago en efectivo, sin contar retenciones.
payment.paid_at	Fecha y hora del pago.
payment.payment_method	Forma de pago. Puede ser cualquiera de las formas de pago definidas por la empresa (por ejemplo EFECTIVO, TRANSFERENCIA BANCARIA) o las del sistema (WOMPI - PSE, CONVENIO BANCOLOMBIA); el sistema receptor no debe suponer una lista fija.
payment.reference	Referencia del pago, cuando existe.
payment.type	Tipo de pago: SERVICIOS, SUSCRIPCION, OTROS INGRESOS o FINANCIACION.
payment.invoice_ids	Facturas que cubre el pago.
service.id	Servicio al que se aplicó el pago.
subscriber.id y subscriber.name	Identificador y nombre del cliente.
agency.id y agency.name	Agencia dueña del pago.

Cabeceras del envío

Cada solicitud incluye estas cabeceras:

Cabecera	Para qué sirve
X-ISPManager-Event	El evento del aviso (payment.created).
X-ISPManager-Delivery	Un identificador único del envío. Se mantiene igual en los reintentos, así que sirve para no procesar dos veces el mismo aviso.
X-ISPManager-Timestamp	El momento en que se firmó el aviso, en segundos desde 1970 (formato Unix).
X-ISPManager-Signature	La firma del aviso, en la forma sha256=....

Cómo validar la firma

El sistema receptor debe recalcular la firma con el secreto y compararla con la que llega. La propia pantalla de edición muestra el procedimiento:

1. Una con un punto el contenido de X-ISPManager-Timestamp y el cuerpo exacto recibido: timestamp + . + cuerpo.
2. Calcule el HMAC SHA-256 de ese texto usando el secreto de firma.
3. Compare el resultado con el valor que viene en X-ISPManager-Signature (después de sha256=).

Para evitar que alguien reenvíe un aviso viejo, conviene rechazar los avisos cuyo X-ISPManager-Timestamp tenga más de 300 segundos (5 minutos) de antigüedad.

El sistema receptor debe responder con un código de éxito (2xx) en menos de 30 segundos y sin redirecciones. Solo los errores de servidor (5xx), 408 y 429 hacen que ISPManager reintente el envío más tarde.

Próximos pasos

• Pagos con Retenciones: cómo se registran en caja los pagos que disparan estos avisos.
• Recaudo Bancolombia: otra vía de pago que también dispara los avisos.
• Personalizar las Notificaciones: los avisos automáticos que se envían al cliente por WhatsApp y SMS.