Los webhooks de Level envían eventos de alertas, dispositivos y grupos a un endpoint HTTP que usted controla. Úselos cuando su integración necesite actualizaciones basadas en eventos en lugar de consultar la API pública.

Este artículo cubre el formato de solicitud y el comportamiento del receptor. Para crear un webhook, elegir eventos, gestionar el secreto y revisar los registros de entrega en Level, consulte Configuración de Webhooks.

Para los esquemas de carga útil por evento, consulte la Documentación para desarrolladores de Level.

ℹ️ NOTA: Estos son webhooks de eventos salientes. Para iniciar una automatización de Level desde una solicitud entrante, consulte Disparador de Webhook.

Antes de comenzar

Necesita:

Acceso de administrador para configurar el webhook en Level.
Un endpoint HTTPS accesible públicamente.
Un secreto de alta entropía compartido entre Level y su receptor.
Una forma de almacenar los IDs de eventos procesados o de hacer idempotente el manejo de eventos.

Configure el destino y la selección de eventos en Ajustes → Webhooks siguiendo Configuración de Webhooks.

Formato de solicitud

Level envía un HTTP POST con:

Content-Type: application/json

Cuando el webhook tiene un secreto, Level también envía:

X-Level-Signature: sha256=

Cada evento utiliza este sobre JSON:

{  "event_type": "device_created",  "event_id": "550e8400-e29b-41d4-a716-446655440000",  "occurred_at": "2026-03-13T18:30:00.000Z",  "data": {    "id": "..."  }}

Campo	Tipo	Descripción
`event_type`	cadena	Identifica el tipo de evento.
`event_id`	UUID	Identifica el evento y permanece igual cuando la carga útil se entrega nuevamente.
`occurred_at`	Fecha y hora ISO 8601 en UTC	Hora en que se generó el evento.
`data`	objeto	Datos del evento específicos del recurso.

Use la referencia de carga útil de webhook para el esquema de cada data objeto.

Tipos de eventos

`event_type`	Cuándo se envía
`alert_active`	Se genera una nueva alerta.
`alert_resolved`	Se resuelve una alerta existente.
`device_created`	Se agrega un dispositivo.
`device_updated`	Los datos o la configuración del dispositivo cambian.
`device_deleted`	Se elimina un dispositivo.
`group_created`	Se crea un grupo de dispositivos.
`group_updated`	El nombre o la configuración de un grupo cambia.
`group_deleted`	Se elimina un grupo.

Los tipos de eventos entregados a un endpoint dependen de la selección guardada en Ajustes → Webhooks.

Verificar la firma

Cuando se configura un secreto, Level calcula HMAC-SHA256 sobre el cuerpo exacto de la solicitud JSON.

Verifique la solicitud antes de analizar o procesar el cuerpo:

Lea el cuerpo de la solicitud sin procesar como bytes.
Calcule HMAC-SHA256 sobre esos bytes exactos, usando el secreto del webhook como clave.
Codifique el resumen como hexadecimal en minúsculas.
Agregue el prefijo del resumen con sha256=.
Compárelo con X-Level-Signature usando una comparación en tiempo constante.
Rechace la solicitud si los valores no coinciden.

⚠️ ADVERTENCIA: Analizar y volver a serializar el JSON antes de calcular el HMAC puede cambiar los espacios en blanco o el formato de los campos y producir un resumen diferente. Verifique el cuerpo de la solicitud sin procesar.

El encabezado de firma se omite si el webhook no tiene secreto. Configure un secreto para los destinos de producción.

Procesar eventos de forma segura

Un receptor debería:

Aceptar solicitudes solo a través de HTTPS.
Verificar X-Level-Signature antes de confiar en la carga útil.
Validar event_type, event_id, occurred_at, y el data esquema.
Registrar event_id o usar una operación idempotente.
Poner el trabajo más extenso en su propia cola.
Devolver una respuesta exitosa 2xx después de aceptar el evento.

Las solicitudes fallidas pueden reintentarse automáticamente, y un administrador puede volver a ejecutar manualmente una entrega desde Level. Cualquiera de los dos caminos puede enviar el mismo event_id más de una vez.

💡 CONSEJO: Use event_id como clave de idempotencia. Si su receptor ya lo ha procesado, devuelva éxito sin repetir la operación.

Solucionar problemas de entrega

Use Ajustes → Webhooks → Solicitudes para revisar los intentos registrados. Los detalles de la solicitud pueden incluir:

Estado de entrega.
Estado de respuesta HTTP.
URL de destino.
Hora del evento.
Error de conexión o HTTP.
Cuerpo de la respuesta.

Después de corregir el destino, use Volver a ejecutar solicitud para reenviar la carga útil almacenada. Una nueva ejecución usa el mismo ID de evento, por lo que el receptor debe manejarlo como un posible duplicado.

Consulte Configuración de Webhooks para el flujo de trabajo completo de configuración y registro de entregas.

Webhooks: Guía para desarrolladores