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 payload 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 el manejo de eventos idempotente.

Configure el destino y la selección de eventos en Configuración → 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 el payload se entrega nuevamente.
`occurred_at`	Fecha y hora ISO 8601 en UTC	Hora en que se generó el evento.
`data`	objeto	Datos de evento específicos del recurso.

Utilice la referencia de payload 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`	Cambian los datos o la configuración del dispositivo.
`device_deleted`	Se elimina un dispositivo.
`group_created`	Se crea un grupo de dispositivos.
`group_updated`	Cambia el nombre o la configuración de un grupo.
`group_deleted`	Se elimina un grupo.

Los tipos de eventos entregados a un endpoint dependen de la selección guardada en Configuración → 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, utilizando el secreto del webhook como clave.
Codifique el resumen como hexadecimal en minúsculas.
Anteponga al resumen el prefijo sha256=.
Compárelo con X-Level-Signature utilizando 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 debe:

Aceptar solicitudes solo a través de HTTPS.
Verificar X-Level-Signature antes de confiar en el payload.
Validar event_type, event_id, occurred_at, y el data esquema.
Registrar event_id o usar una operación idempotente.
Coloque el trabajo más extenso en su propia cola.
Devolver una respuesta exitosa 2xx respuesta 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 las dos vías 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 Configuración → 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 el payload almacenado. Una nueva ejecución utiliza 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