Introducción

Configure callbacks HTTP para enviar eventos de Level a sus propios sistemas en tiempo real. Cuando ocurre algo 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 usted especifique, para que pueda reaccionar en sus propias herramientas sin consultar la API.

Para la referencia completa de la API y los esquemas de carga por evento, consulte la Level Developer Documentation.

⚙️ REQUISITOS PREVIOS

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

Webhook Settings

Navegue a Settings → Webhooks. La página tiene dos pestañas:

Webhooks — sus webhooks configurados
Requests — el registro de entregas de todas las solicitudes salientes

Creación de un Webhook

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

2. Ingrese la URL. Aquí es donde Level enviará los datos del evento mediante POST. Use HTTPS.

3. (Opcional) Ingrese un Secret. Level usa esto para firmar cada solicitud saliente para que su endpoint pueda verificar que la carga provino de Level.

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

⚠️ ADVERTENCIA: El secreto no puede verse de nuevo después de guardar. Cópielo en algún lugar antes de hacer clic en Add webhook — lo necesitará en el código de su endpoint para verificar las firmas.

4.. El Enabled 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 Events to send, elija qué activa este webhook:

Send all event types — Level envía cada tipo de evento, incluidos los nuevos que se agreguen en el futuro.
Select types to send — elija de la lista a continuación.

Tipos de Eventos Disponibles

Evento	Cuándo se activa
Alert active	Se genera una nueva alerta en un dispositivo
Alert resolved	Una alerta existente es resuelta
Device created	Se agrega un nuevo dispositivo a su cuenta
Device deleted	Se elimina un dispositivo de su cuenta
Device updated	Los datos o la configuración de un dispositivo existente cambian
Group created	Se crea un nuevo grupo de dispositivos
Group deleted	Un grupo de dispositivos es eliminado permanentemente
Group updated	El nombre o la configuración de un grupo cambia

ℹ️ NOTA: Si usa Select types to send, los nuevos tipos de eventos agregados a Level en el futuro no se incluirán automáticamente. Cambie a Send all event types si desea una entrega compatible con versiones futuras.

6. Haga clic en Add webhook para guardar.

Estructura del Payload

Cada entrega de webhook — independientemente del tipo de evento — usa 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`	string	Uno de los 8 tipos de eventos listados anteriormente
`event_id`	UUID	Único por evento; estable en los reintentos — úselo para deduplicar
`occurred_at`	ISO 8601 datetime (UTC)	Cuándo se generó el evento
`data`	object	Payload específico del recurso para este evento

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

ℹ️ NOTA: Para los esquemas completos por evento, consulte la data esquemas, consulte la Level Developer Documentation.

Verificación de Firmas de Solicitudes

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 cadena.
Calcule HMAC-SHA256 de esa cadena usando su secreto como clave.
Agregue el prefijo al resultado con sha256= y compárelo con el valor X-Level-Signature del encabezado.
Si coinciden, la solicitud proviene de Level.

ℹ️ NOTA: El X-Level-Signature El encabezado 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 Requests muestra cada solicitud saliente que Level ha intentado en todos los webhooks configurados.

Cada fila muestra:

Status — insignia de éxito o fallo
Status code — el código de respuesta HTTP de su endpoint (o -- si la conexión falló antes de recibir una respuesta)
URL — el destino de esa solicitud

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

El panel de detalles muestra:

Event time — cuándo ocurrió el evento
Status code — respuesta HTTP de su servidor
Full URL — la URL exacta a la que Level envió
Error message — el error de conexión o HTTP, si lo hay
Response body — lo que devolvió su endpoint (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 intentarlo y registra el fallo final. No se genera ninguna alerta y el webhook no se deshabilita.

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

Reejecutar una Solicitud Fallida Manualmente

Si ha solucionado el problema subyacente y no desea esperar al próximo reintento, haga clic en Re-run request en la parte inferior del panel de detalles. Level reenvía el payload original de inmediato.

⚠️ ADVERTENCIA: Re-run request envía el mismo payload de nuevo. Si su endpoint 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 aparece listado con su URL y estado habilitado. Desde allí puede editar la configuración, activarlo o desactivarlo, o eliminarlo.

ℹ️ NOTA: Deshabilitar un webhook detiene la entrega sin eliminarlo ni su historial de solicitudes. Úsalo cuando tu endpoint esté en mantenimiento.

Preguntas frecuentes

¿Qué formato utiliza Level para los payloads de webhooks? Level envía un HTTP POST con un cuerpo JSON. Cada evento utiliza el mismo envelope: event_type, event_id, occurred_at, y data. El data El objeto contiene el payload específico del recurso para ese tipo de evento. Consulta la Level Developer Documentation para ver los esquemas completos por evento.
¿Cómo verifico que una solicitud proviene de Level? Establece un secreto en el webhook. Level incluye un X-Level-Signature encabezado con formato sha256=<hex_digest> en cada solicitud. Calcula el HMAC-SHA256 del cuerpo de la solicitud sin procesar usando tu secreto y compáralo con el valor del encabezado. Consulta Verificación de firmas de solicitudes anterior.
¿Quién puede crear y gestionar webhooks? La configuración de webhooks —incluido el registro de solicitudes— está restringida a los administradores. Solo los técnicos con acceso de administrador a tu organización de Level pueden crear, editar, ver o eliminar webhooks.
Todas mis solicitudes aparecen como fallidas. ¿Qué debo revisar? Abre una solicitud fallida en el panel de detalles y lee el mensaje de error y el cuerpo de la respuesta. Causas comunes: la URL no es accesible públicamente, tu endpoint devolvió un código de estado no 2xx, o la URL fue escrita incorrectamente. Soluciona el problema subyacente y luego usa Volver a ejecutar la solicitud para reintentar sin esperar la ventana de reintento automático.
¿Puedo enviar los mismos eventos a múltiples endpoints? Sí. Crea un webhook separado para cada URL de destino. Cada webhook se suscribe a tipos de eventos de forma independiente.
¿Qué ocurre después de 3 intentos de entrega fallidos? Level deja de reintentar y registra el fallo final. El webhook permanece habilitado y continuará intentando futuros eventos — solo esa entrega específica se abandona. Aún puedes volver a ejecutarla manualmente desde la pestaña Solicitudes.
Perdí mi secreto de webhook. ¿Puedo recuperarlo? No. El secreto no puede consultarse después de guardar el webhook. Edita el webhook para establecer un nuevo secreto y luego actualiza el código de tu endpoint para usar el nuevo valor.

Configuración de Webhooks