Webhooks

Configure suscripciones de webhook para recibir notificaciones en tiempo real en su sistema externo cuando ocurran eventos importantes en ALTUM ERP.

Requisitos previos

• Permiso integraciones.webhook.gestionar en ALTUM ERP.
• Un endpoint HTTPS en su servidor capaz de recibir peticiones POST con cuerpo JSON.

Pantalla de Webhooks

Navegue a Integraciones → Webhooks para ver y gestionar las suscripciones activas.

La tabla muestra las suscripciones existentes con las columnas:

Columna	Descripción
URL de destino	Endpoint donde ALTUM ERP enviará las notificaciones.
Eventos suscritos	Lista de tipos de evento que activarán entregas a este webhook.
Tasa de éxito	Porcentaje de entregas exitosas sobre el total de intentos.
Última entrega	Fecha y hora de la última entrega exitosa.
Estado	Activo o inactivo.

Crear una suscripción de webhook

Paso 1: Abrir el formulario de nueva suscripción

Haga clic en el botón Nueva Suscripción en la pantalla de Webhooks.

Paso 2: Completar los datos

Campo	Descripción
URL	Dirección HTTPS de su endpoint (obligatorio). Debe comenzar con https://. Durante desarrollo local se permite http://localhost.
Descripción	Texto opcional para identificar el propósito de la suscripción.
Eventos	Selección múltiple de los tipos de evento a recibir. Debe elegir al menos uno.

Paso 3: Guardar y copiar el signing secret

Al guardar, el sistema genera un signing secret único (64 caracteres hexadecimales). Este secret se muestra una sola vez en un diálogo de confirmación.

Precaución

Copie el signing secret antes de cerrar el diálogo. No es posible recuperarlo después. Si lo pierde, deberá regenerarlo (ver sección Regenerar el Signing Secret).

El signing secret se usa para verificar la autenticidad de las notificaciones recibidas en su endpoint (ver sección Seguridad y verificación de firma).

Verificar entregas

Abra el detalle de una suscripción haciendo clic en su fila para ver el historial de entregas individuales.

Cada entrega muestra:

Campo	Descripción
Estado	PENDING, DELIVERED, RETRYING o FAILED.
Código HTTP	Código de respuesta devuelto por su endpoint.
Fecha del intento	Fecha y hora del intento de entrega.
Duración	Tiempo de respuesta del endpoint en milisegundos.

Reintentar una entrega fallida

Para reenviar manualmente una entrega con estado FAILED, use el botón Reintentar en el detalle de la entrega. El sistema envia una nueva petición con el mismo payload original.

Habilitar o deshabilitar una suscripción

Use el interruptor de estado en la tabla de suscripciones para activar o desactivar una suscripción sin eliminarla. Las suscripciones inactivas no reciben entregas.

Enviar un ping de prueba

Desde el detalle de una suscripción, use el botón Enviar Ping para enviar una notificación de prueba a su endpoint. El ping confirma que la URL está accesible y que la firma se verifica correctamente.

Regenerar el Signing Secret

Si el signing secret se compromete, use el botón Regenerar Secret en el detalle de la suscripción. El nuevo secret se mostrará una sola vez, igual que al crear la suscripción.

Precaución

Al regenerar el secret, todas las verificaciones de firma en su endpoint que usen el secret anterior comenzarán a fallar. Actualice su código inmediatamente después de copiar el nuevo secret.

Seguridad y verificación de firma

Cada entrega incluye el header X-Altum-Signature con una firma HMAC-SHA256 del cuerpo JSON usando el signing secret. Para verificar la autenticidad:

firma = HMAC-SHA256(signing_secret, cuerpo_json_raw)
X-Altum-Signature: sha256=<firma_en_hex>

Compare el valor calculado con el valor recibido en el header. Si no coinciden, rechace la petición.

Reintentos automáticos

Cuando su endpoint responde con un código que no es 2xx (o no responde dentro del timeout), ALTUM ERP reintenta la entrega con el siguiente ciclo de estados:

Estado	Descripción
PENDING	Primer intento en cola.
RETRYING	Al menos un intento falló; próximo reintento programado.
DELIVERED	Respuesta HTTP 2xx recibida; entrega exitosa.
FAILED	Todos los reintentos se agotaron sin respuesta exitosa.

Límites y restricciones

• Máximo 20 suscripciones activas por empresa.
• La URL debe usar HTTPS en producción (http://localhost únicamente para desarrollo).
• Cada suscripción puede suscribirse a uno o más de los 15 tipos de evento disponibles (ver Catálogo de Eventos).

Casos frecuentes

Mi endpoint recibe las notificaciones pero la firma no coincide. Asegúrese de calcular la firma sobre el cuerpo raw (bytes exactos), no sobre el JSON parseado y re-serializado. Cualquier diferencia de espacios o saltos de línea invalidará la firma.

Las entregas quedan en estado FAILED. Verifique que su endpoint responde con HTTP 2xx dentro del tiempo de respuesta esperado. Revise que la URL sea accesible desde internet y que no requiera autenticación adicional.

Llegué al límite de 20 suscripciones. Elimine suscripciones que ya no se usen o desactive las innecesarias para liberar cupo.