Help CenterOpen app

Disparadores

Automatizaciones por monitor que llaman a sistemas externos en transiciones de estado o coincidencias de payload. Las llamadas salientes se validan y limitan para evitar destinos inseguros y bucles descontrolados.

TIPOS DE DISPARADOR

  • Webhook: esquema JSON fijo con cabeceras de firma HMAC-SHA256. Elige esto cuando el receptor espera el formato KEEPitALIVE.
  • HTTP Request: método, cabeceras y plantilla de cuerpo totalmente personalizados con variables de marcador. Elige esto para integraciones a medida.
  • Notify: envía una notificación a través de tus canales de alerta configurados (Email, Discord, Slack, etc.) con una plantilla de título/cuerpo personalizada.
  • Incident: abre un incidente de caída/degradación cuando una condición de payload coincide y luego lo resuelve automáticamente cuando un evento posterior limpia la condición (o cuando desactivas/eliminas el disparador). Una fuente totalmente silenciosa no se resuelve automáticamente: consulta Condiciones.
Sección de conceptos básicos del trigger con los cuatro tipos: Webhook, HTTP Request, Notificación e Incidente
Elige primero el tipo - es lo que decide qué hace el trigger cuando se dispara.

EVENTOS

Nueve eventos: down, recovered, degraded, flapping_start, flapping_stop, maintenance_start, maintenance_end, signal y payload. signal se dispara para los latidos de heartbeat del Receptor de eventos. payload se dispara para comprobaciones que capturaron un payload de respuesta, especialmente monitores API.

Sección de eventos del trigger con los modos Cambio de estado y Cada payload, y casillas para cae, se recupera, se degrada, empieza a oscilar y deja de oscilar
Cambio de estado se dispara solo en transiciones. Cada payload se dispara en cada comprobación, que es lo que quieres para monitores receptores de eventos.

VARIABLES DE PLANTILLA

Usa estos en las plantillas de cuerpo/cabeceras/URL de HTTP Request y de título de Notify:

Marcadores disponibles
{{monitor.id}}     {{monitor.ref}}     {{monitor.name}}    {{monitor.url}}     {{monitor.type}}
{{event.id}}       - stable per-fire id (same value across the retry; use it to dedupe)
{{event.type}}     {{event.status}}    {{event.latency_ms}}
{{event.status_code}}  {{event.error}}  {{event.timestamp}}
{{check.id}}       - id of the originating check (omitted for synthetic events)
{{payload}}        - full check payload as raw string
{{payload.KEY}}    - dot-path into the JSON payload (e.g. {{payload.status}})

Nota: monitor.id y monitor.ref se resuelven ambos a la referencia pública del monitor, nunca a un id interno de base de datos. Basa tus sistemas posteriores en ella.

Plantilla de cuerpo de HTTP Request (JSON)
{
  "source": "keepitalive",
  "monitor": "{{monitor.name}}",
  "event": "{{event.type}}",
  "status": "{{event.status}}",
  "latency_ms": "{{event.latency_ms}}",
  "error": "{{event.error}}",
  "at": "{{event.timestamp}}"
}

CONDICIONES

Los disparadores pueden condicionar el disparo con una expresión contra el payload de comprobación almacenado. Gramática: ==, !=, >, <, >=, <=, contains, exists, and, or, not, paréntesis, rutas con punto. Ejemplo: payload.failed_jobs > 0 and payload.status == "error". Los disparadores de incidente requieren una condición. Abren el incidente mientras la expresión coincide y lo resuelven cuando la expresión deja de coincidir. Cómo funciona la resolución: el incidente se resuelve automáticamente cuando una comprobación o payload posterior reevalúa el mismo disparador y la expresión pasa a ser falsa. También se cierra de inmediato si desactivas o eliminas el disparador. Importante: el silencio no es recuperación. Si la fuente deja de enviar payloads/heartbeats por completo, no hay evento que limpie la condición, por lo que el incidente permanece abierto hasta que llegue un nuevo evento o lo resuelvas manualmente. Esto es intencionado: nunca tratamos "sin datos" como "recuperado", porque para una fuente de payload/signal el silencio puede ser la verdadera caída.

Sección de condiciones del trigger con una expresión que filtra por payload.failed_jobs y payload.status
Las condiciones leen el payload con rutas de puntos simples - aquí no se usan llaves, a diferencia de las plantillas de cuerpo.
Qué contiene el payload, según el tipo de monitor
Heartbeat / event receiver - your posted JSON stays at the top:
  payload.failed_jobs, payload.status
  What we observed sits under beat, so it cannot shadow yours:
  payload.beat.received_at, payload.beat.exit_code,
  payload.beat.duration_ms
  (those three are also copied flat when you do not use the name)

API monitor - the response is wrapped:
  payload.body.<what the server returned>
  payload.status_code, payload.headers, payload.assertions

So an API check of a status endpoint reads
  payload.body.status.indicator - not payload.status.indicator.
Condición de automatización de incidente
Open degraded incident when:
payload.failed_jobs > 0 or payload.status == "error"

Auto-resolves when a later event makes that expression false,
or when you disable/delete the trigger.
A source that goes fully silent will NOT auto-resolve.

FORMA DEL PAYLOAD DEL WEBHOOK

Los disparadores de webhook hacen POST de este cuerpo JSON fijo. Basa tu manejador en event_id (deduplicación) y monitor.ref (identidad):

Cuerpo del POST
{
  "event_id": "9f2c1ab4e5d6...",   // stable per fire, repeats on retry
  "event": "down",
  "monitor": {
    "id": "mon_abc123", "ref": "mon_abc123",
    "name": "API", "url": "https://api.example.com", "type": "http"
  },
  "check": {
    "id": 84213, "status": "down",
    "latency_ms": 234, "status_code": 503, "error": "...",
    "payload": { }
  },
  "timestamp": "2026-06-27T12:00:00Z"
}

VERIFICACIÓN DE FIRMA (WEBHOOK)

Cuando un disparador de webhook tiene un secreto, cada entrega lleva X-Timestamp y X-Signature-256. Vuelve a calcular y compara para rechazar llamadas falsificadas:

Verificar (pseudocódigo)
signed   = X-Timestamp + "." + raw_request_body
expected = "sha256=" + hex(hmac_sha256(secret, signed))
reject unless constant_time_equals(expected, X-Signature-256)
// optional: reject if X-Timestamp is older than a few minutes

SEMÁNTICA DE ENTREGA

  • Idempotencia: X-KEEPitALIVE-Event-ID (también event_id en el cuerpo / {{event.id}}) se genera una vez por disparo y se reutiliza en los reintentos. Deduplica con él para que un reintento que llega tras un primer intento lento no se procese dos veces.
  • Política de reintentos: los disparadores de red pueden reintentar 0-3 veces con un retraso de 5-600 segundos. Los disparadores Notify no reintentan para evitar notificaciones duplicadas visibles para el usuario.
  • Los redireccionamientos NO se siguen: una respuesta 3xx cuenta como fallo de entrega. Apunta la URL al destino final.
  • Rompedor de bucles: las entregas salientes llevan X-KEEPitALIVE-Depth. Un latido reenviado a un receptor de eventos propaga depth+1, y los disparadores de red dejan de dispararse en la profundidad 3, por lo que las cadenas disparador -> receptor de eventos se limitan a 3 saltos.

RECETAS DE INTEGRACIÓN

n8n / Make / Zapier: crea un Webhook (n8n) o un catch hook de Custom Webhook (Make/Zapier), pega su URL en un disparador HTTP Request o Webhook. Para los disparadores Webhook, verifica X-Signature-256 en un paso Function/Code antes de actuar; ramifica según {{event.type}} y deduplica con event_id.

Purga de caché de Cloudflare (disparador HTTP Request)
Method: POST
URL:    https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache
Headers: Authorization: Bearer <API_TOKEN>
         Content-Type: application/json
Body:   { "purge_everything": true }
// Tip: gate on {{event.type}} == recovered to purge after a deploy recovers.
Webhook de Home Assistant (disparador HTTP Request)
Method: POST
URL:    https://<HA_HOST>/api/webhook/<WEBHOOK_ID>
Body:   { "monitor": "{{monitor.name}}", "status": "{{event.status}}",
          "event": "{{event.type}}", "event_id": "{{event.id}}" }
Webhook genérico "reiniciar servicio"
Method: POST
URL:    https://ops.example.com/hooks/restart
Headers: X-Auth-Token: <TOKEN>
Body:   { "service": "{{monitor.name}}", "reason": "{{event.error}}",
          "ref": "{{monitor.ref}}", "event_id": "{{event.id}}" }
// Make the receiver idempotent on event_id so a retry never double-restarts.

SEGURIDAD

  • El cortacircuitos desactiva un disparador tras 10 fallos consecutivos (el propietario recibe una notificación en la app).
  • Política de oscilación: la misma regla de 4-en-10-min se aplica por disparador.
  • Los disparadores Notify registran un resultado de entrega por canal (entregado / parcial / fallido) en el registro de ejecución.
  • El secreto del webhook se muestra una vez al crear/rotar; se oculta en todas las respuestas posteriores.
SiguientePáginas de estado