Introducción

Configure devoluciones de llamada HTTP para enviar eventos de Level a sus propios sistemas en tiempo real. Cuando algo ocurre en Level — se activa 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 obtener la referencia completa de la API y esquemas de carga 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

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

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

Crear un Webhook

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

2. Ingrese la URL de destino URL . Aquí es donde Level enviará los datos del evento. 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 proviene de Level.

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

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

4.. El conmutador Habilitado está activado de forma predeterminada. Déjelo activado para comenzar a recibir eventos inmediatamente. 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 para enviar — elija de la lista a continuación.

Tipos de eventos disponibles

Evento	Cuándo se activa
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 para 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

Cada entrega de webhook — independientemente del tipo de evento — utiliza el mismo sobre 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 listados arriba
`event_id`	UUID	Único por evento; estable entre reintentos — úselo para deduplicar
`occurred_at`	Datetime ISO 8601 (UTC)	Cuándo se generó el evento
`data`	objeto	Carga específica de recurso para este evento

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

ℹ️ NOTA: Para esquemas 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 la solicitud JSON sin procesar como una cadena.
Calcule HMAC-SHA256 de esa cadena usando su secreto como clave.
Anteponga el resultado con sha256= y compárelo con el valor del encabezado X-Level-Signature.
Si coinciden, la solicitud proviene 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 agregarlo.

Revisión de registros de entrega

La pestaña Solicitudes muestra todas las solicitudes salientes que Level ha intentado en todos los webhooks configurados.

Cada fila muestra:

Estado — distintivo 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 detalle.

El panel de detalle muestra:

Hora del evento — cuándo ocurrió el evento
Código de estado — respuesta HTTP de su servidor
URL completa — la URL exacta que Level envió
Mensaje de error — el error de conexión o HTTP, si existe
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 a 60 segundos. Después de 3 intentos fallidos, Level deja de intentar y registra el error final. No se genera ninguna alerta y el webhook no se desactiva.

ℹ️ 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 parte.

Reejecutar una solicitud fallida manualmente

Si ha corregido el problema subyacente y no desea esperar al siguiente reintento, haga clic en Reejecutar solicitud en la parte inferior del panel de detalle. Level reenvía la carga original inmediatamente.

⚠️ ADVERTENCIA: Reejecutar solicitud envía la misma carga 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, activarla o desactivarla, o eliminarla.

ℹ️ NOTA: Desactivar 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 de webhooks? Level envía un HTTP POST con un cuerpo JSON. Cada evento utiliza el mismo sobre: event_type, event_id, occurred_at , y data. El objeto data contiene la carga 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 la solicitud sin procesar usando su secreto, luego compare con el valor del encabezado. Consulte Verificación de firmas de solicitud arriba.
¿Quién puede crear y administrar webhooks? La configuración de webhooks — incluido el registro de solicitudes — se limita a administradores. Solo los técnicos con acceso de administrador a su organización Level pueden crear, editar, ver o eliminar webhooks.
Todas mis solicitudes muestran Error. ¿Qué debo verificar? Abra una solicitud fallida en el panel de detalle y lea el mensaje de error y el cuerpo de respuesta. Causas comunes: la URL no es accesible públicamente, su punto final devolvió un código de estado que no es 2xx, o la URL fue mal escrita. Corrija el problema subyacente, luego use Reejecutar solicitud 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 error final. 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 guardar el webhook. Edite el webhook para establecer un nuevo secreto, luego actualice su código de punto final para usar el nuevo valor.