Webhooks

Descripción general

Un webhook notifica a otro sistema cuando ocurre un evento del ciclo de vida de un activo. ActivoHQ envía por HTTP POST, a la dirección que usted indique, el mismo contenido que usan las reglas de automatización: activo dado de baja, revaluado, retirado, devuelto, retiro vencido y varianza RFID detectada.

Es la vía para integrar ActivoHQ con su ERP, su mesa de ayuda, un canal de mensajería o cualquier servicio propio, sin que ese sistema tenga que consultar la API periódicamente.

Las entregas se reintentan automáticamente y su resultado queda visible en la misma pantalla.

Cómo llegar

Configuración > Webhooks

URL directa: /settings/webhooks

Suscripciones de webhooks a los eventos del ciclo de vida

Conceptos clave

Término	Definición
Suscripción	Una URL más la lista de eventos que le interesan.
Entrega	Cada intento de envío del contenido de un evento a la URL suscrita.
Secreto	Clave opcional con la que ActivoHQ firma el contenido, para que su sistema compruebe que el mensaje proviene realmente de ActivoHQ.
Firma	Valor HMAC-SHA256 del cuerpo del mensaje, enviado en la cabecera `X-ActivoHQ-Signature` en formato hexadecimal en minúsculas.

Eventos disponibles

AssetDisposed, AssetRevalued, AssetCheckedOut, AssetCheckedIn, AssetCheckoutOverdue, RfidVarianceDetected

Son los mismos eventos que usan las Reglas de automatización; la pantalla los muestra como valores válidos junto al campo Eventos.

Cómo usarla

Crear un webhook

Haga clic en Nuevo.
En el diálogo Nuevo Webhook complete:
- URL (obligatoria): dirección que recibirá el POST, por ejemplo https://example.com/webhooks/activohq.
- Eventos (obligatorio): lista separada por comas con uno o varios de los eventos válidos.
- Secreto (opcional): clave para firmar el contenido.
- Activo: marcado por omisión.
Haga clic en Guardar.

Si la URL está vacía o ningún evento indicado es válido, el sistema avisa que debe ingresar una URL y al menos un tipo de evento válido.

Revisar las entregas

La sección Entregas recientes muestra, para cada intento:

Columna	Descripción
Creado	Fecha y hora en que se generó la entrega.
Evento	Evento que la originó.
Estado	Enviado, Fallido o Pendiente.
Intentos	Cuántos intentos se han realizado.
Último error	Motivo del último fallo, cuando lo hubo.

Reintentos

ActivoHQ procesa la cola de entregas cada minuto y reintenta las que no fueron aceptadas hasta un máximo de 5 intentos. Mientras quedan intentos disponibles, la entrega permanece Pendiente; agotados los intentos, pasa a Fallido.

Verificar la firma en su sistema

Cuando la suscripción tiene Secreto, cada POST incluye la cabecera X-ActivoHQ-Signature con el HMAC-SHA256 del cuerpo tal como se recibió, en hexadecimal minúsculas y sin prefijo. Su sistema debe recalcular ese HMAC con el mismo secreto sobre el cuerpo original y compararlo antes de procesar el mensaje.

Editar o eliminar webhooks

Para editar, haga clic en la URL en la tabla.
Para eliminar uno, use Eliminar en el menú contextual; para varios, marque las casillas y use Eliminar (N).
Para suspender los envíos sin borrar la suscripción, desmarque Activo.

Campos

Campo	Tipo	Obligatorio	Descripción	Validación
URL	Texto	Sí	Dirección que recibe el POST.	Debe indicarse una URL. Solo se permiten destinos públicos en Internet: no se aceptan direcciones internas de red, locales ni de servicios internos de la nube.
Eventos	Texto	Sí	Lista de eventos separada por comas.	Al menos uno debe ser válido.
Secreto (opcional)	Texto	No	Clave para firmar el contenido con HMAC-SHA256.	Ninguna.
Activo	Casilla de verificación	No	Las suscripciones inactivas no reciben entregas.	Ninguna.

Notas

Las suscripciones son por empresa.
Su servicio debe responder con un código de éxito HTTP; cualquier otra respuesta cuenta como intento fallido y se reintenta.
Diseñe su receptor para tolerar entregas repetidas del mismo evento: un reintento puede llegar después de que su sistema ya procesó el mensaje.
Para avisar a personas en lugar de a un sistema, use una regla de automatización con el mismo evento.

Problemas comunes

Síntoma	Causa probable	Solución
Todas las entregas aparecen Fallido.	La URL no responde, responde con error, o exige autenticación adicional.	Revise Último error, valide la URL desde fuera de su red y ajuste su receptor.
No se guarda el webhook.	La URL está vacía o los eventos escritos no son válidos.	Copie los nombres de evento exactamente como los muestra la pantalla.
La URL interna de la empresa es rechazada.	Solo se aceptan destinos públicos, por seguridad.	Exponga un extremo público (por ejemplo, una pasarela) que reenvíe a su red interna.
Mi sistema recibe el evento dos veces.	Un reintento se cruzó con una entrega que sí llegó.	Haga idempotente el procesamiento en su receptor.
La firma no coincide.	Se recalculó el HMAC sobre un cuerpo ya transformado.	Firme y verifique siempre sobre el cuerpo original recibido.

Relacionado

¿Te resultó útil esta página?

Anterior Reglas de automatización Siguiente Diseñador de reportes