Configure devoluciones de llamada HTTP para enviar eventos de Level a sus propios sistemas en tiempo real. Cuando sucede algo en Level — se genera una nueva alerta, se agrega un dispositivo, se actualiza un grupo — Level envía una solicitud POST a la URL que especifique, para que pueda reaccionar en sus propias herramientas sin sondear la API.

Para la referencia completa de la API y los esquemas de carga útil por evento, consulte la documentación para desarrolladores de Level.

⚙️ REQUISITOS PREVIOS

Un punto final HTTPS accesible públicamente listo para recibir solicitudes POST con un cuerpo JSON.
Acceso de administrador a su organización Level.

Configuración de webhooks

Vaya a Configuración → Webhooks. La página tiene dos pestañas:

Webhooks — sus webhooks configurados
Solicitudes — el registro de entrega de todas las solicitudes salientes

Creación de un webhook

1. Haga clic en + Agregar webhook (arriba a la derecha) o + Crear webhook (estado vacío).

2. Ingrese la URL de destino. Aquí es donde Level enviará datos de eventos. Use HTTPS.

3. (Opcional) Ingrese un Secreto. Level lo usa para firmar cada solicitud saliente para que su punto final pueda verificar que la carga útil proviene de Level.

💡 CONSEJO: Genere su secreto con un administrador de contraseñas o openssl rand -hex 32. Use una cadena aleatoria de alta entropía.

⚠️ ADVERTENCIA: El secreto no se puede ver nuevamente después de guardarlo. Cópielo en algún lugar antes de hacer clic en Agregar webhook — lo necesitará en el código de su punto final para verificar firmas.

4. El interruptor Habilitado está activado de forma predeterminada. Déjelo activado para comenzar a recibir eventos de inmediato. Desactívelo para pausar la entrega sin eliminar el webhook.

5. En Eventos a enviar, elija qué activa este webhook:

Enviar todos los tipos de eventos — Level envía todos los tipos de eventos, incluidos los nuevos agregados en el futuro.
Seleccionar tipos a enviar — elija de la lista a continuación.

Tipos de eventos disponibles

Evento	Cuándo se dispara
Alerta activa	Se genera una nueva alerta en un dispositivo
Alerta resuelta	Se resuelve una alerta existente
Dispositivo creado	Se agrega un nuevo dispositivo a su cuenta
Dispositivo eliminado	Se elimina un dispositivo de su cuenta
Dispositivo actualizado	Los datos o la configuración de un dispositivo existente cambian
Grupo creado	Se crea un nuevo grupo de dispositivos
Grupo eliminado	Se elimina permanentemente un grupo de dispositivos
Grupo actualizado	El nombre o la configuración de un grupo cambia

ℹ️ NOTA: Si usa Seleccionar tipos a enviar, los nuevos tipos de eventos agregados a Level en el futuro no se incluirán automáticamente. Cambie a Enviar todos los tipos de eventos si desea una entrega compatible con versiones futuras.

6. Haga clic en Agregar webhook para guardar.

Estructura de carga útil

Cada entrega de webhook — independientemente del tipo de evento — usa la misma envoltura JSON:

{
  "event_type": "device_created",
  "event_id": "a3f1b2c4-...",
  "occurred_at": "2026-03-13T18:30:00Z",
  "data": { ... }
}

Campo	Tipo	Descripción
`event_type`	cadena	Uno de los 8 tipos de eventos enumerados arriba
`event_id`	UUID	Único por evento; estable en reintentos — úselo para deduplicar
`occurred_at`	Fecha/hora ISO 8601 (UTC)	Cuándo se generó el evento
`data`	objeto	Carga útil específica de recurso para este evento

💡 CONSEJO: Use event_id para hacer que su punto final sea idempotente. Level reintenta automáticamente las entregas fallidas, por lo que el mismo evento puede llegar más de una vez.

ℹ️ NOTA: Para esquemas de datos completos por evento data, consulte la documentación para desarrolladores de Level.

Verificación de firmas de solicitud

Si configuró un secreto, Level incluye un encabezado X-Level-Signature en cada solicitud. El formato es sha256=<hex_digest>.

Para verificar:

Tome el cuerpo de solicitud JSON sin procesar como una cadena.
Calcule HMAC-SHA256 de esa cadena usando su secreto como clave.
Prefije el resultado con sha256= y compárelo con el valor de encabezado X-Level-Signature.
Si coinciden, la solicitud es de Level.

ℹ️ NOTA: El encabezado X-Level-Signature solo está presente cuando se configura un secreto en el webhook. Si no estableció uno, considere editar el webhook para agregar uno.

Revisión de registros de entrega

La pestaña Solicitudes muestra cada solicitud saliente que Level ha intentado en todos los webhooks configurados.

Cada fila muestra:

Estado — insignia de éxito o error
Código de estado — el código de respuesta HTTP de su punto final (o -- si la conexión falló antes de una respuesta)
URL — el destino de esa solicitud

Haga clic en cualquier fila para abrir el panel de detalles.

El panel de detalles muestra:

Hora del evento — cuándo ocurrió el evento
Código de estado — respuesta HTTP de su servidor
URL completa — la URL exacta a la que Level envió
Mensaje de error — el error de conexión o HTTP, si lo hay
Cuerpo de respuesta — lo que devolvió su punto final (o la salida de error sin procesar)

Reintentos automáticos

Cuando una entrega falla, Level reintenta automáticamente — hasta 3 intentos en total. Cada reintento espera aproximadamente 2 minutos, más un retraso aleatorio de 1–60 segundos. Después de 3 intentos fallidos, Level deja de intentar y registra el fallo final. No se genera ninguna alerta y el webhook no se deshabilita.

ℹ️ NOTA: Debido a que Level reintenta automáticamente, el mismo evento puede entregarse más de una vez. Use event_id para deduplicar de su lado.

Reejecución manual de una solicitud fallida

Si ha corregido el problema subyacente y no desea esperar la próxima ventana de reintento, haga clic en Ejecutar solicitud nuevamente en la parte inferior del panel de detalles. Level reenvía inmediatamente la carga útil original.

⚠️ ADVERTENCIA: Ejecutar solicitud nuevamente envía la misma carga útil nuevamente. Si su punto final no es idempotente, esto puede crear duplicados. Verifique event_id antes de procesar.

Gestión de webhooks existentes

En la pestaña Webhooks, cada webhook configurado se enumera con su URL y estado habilitado. Desde allí puede editar la configuración, habilitarla o deshabilitarla, o eliminarla.

ℹ️ NOTA: Deshabilitar un webhook detiene la entrega sin eliminarlo o su historial de solicitudes. Úselo cuando su punto final esté en mantenimiento.

Preguntas frecuentes

¿Qué formato usa Level para cargas útiles de webhook? Level envía una solicitud HTTP POST con cuerpo JSON. Cada evento usa la misma envoltura: event_type, event_id, occurred_at y data. El objeto data contiene la carga útil específica del recurso para ese tipo de evento. Consulte la documentación para desarrolladores de Level para esquemas completos por evento.
¿Cómo verifico que una solicitud proviene de Level? Establezca un secreto en el webhook. Level incluye un encabezado X-Level-Signature formateado como sha256=<hex_digest> en cada solicitud. Calcule HMAC-SHA256 del cuerpo de solicitud sin procesar usando su secreto, luego compare con el valor de encabezado. Consulte Verificación de firmas de solicitud arriba.
¿Quién puede crear y administrar webhooks? La configuración de webhook — incluido el registro de solicitudes — se restringe a administradores. Solo los técnicos con acceso de administrador a su organización Level pueden crear, editar, ver o eliminar webhooks.
Mis solicitudes muestran todas fallidas. ¿Qué debo verificar? Abra una solicitud fallida en el panel de detalles y lea el mensaje de error y el cuerpo de la respuesta. Causas comunes: la URL no es accesible públicamente, su punto final devolvió un código de estado no-2xx, o la URL fue escrita incorrectamente. Corrija el problema subyacente, luego use Ejecutar solicitud nuevamente para reintentar sin esperar la ventana de reintento automático.
¿Puedo enviar los mismos eventos a múltiples puntos finales? Sí. Cree un webhook separado para cada URL de destino. Cada webhook se suscribe a tipos de eventos de forma independiente.
¿Qué sucede después de 3 intentos de entrega fallidos? Level deja de reintentar y registra el fallo. El webhook permanece habilitado y continuará intentando eventos futuros — solo esa entrega específica se abandona. Aún puede ejecutarla manualmente desde la pestaña Solicitudes.
Perdí mi secreto de webhook. ¿Puedo recuperarlo? No. El secreto no se puede ver después de guardarse el webhook. Edite el webhook para establecer un nuevo secreto, luego actualice el código de su punto final para usar el nuevo valor.