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.
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.
• Cobros automáticos de servicios prepago.

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.
• Reversos de pago por nota crédito.
• Movimientos con valor cero o negativo.

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 aviso no se entrega, ISPManager reintenta varias veces de forma automática, espaciando cada intento.

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.
payment.paid_at	Fecha y hora del pago.
payment.payment_method	Forma de pago (por ejemplo EFECTIVO, WOMPI - PSE).
payment.reference	Referencia del pago, cuando existe.
payment.type	Tipo de pago (por ejemplo SERVICIOS).
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.
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). Si responde con un error, ISPManager reintentará 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.