Help CenterOpen app

Déclencheurs

Automatisations par moniteur qui appellent des systèmes externes lors des transitions d’état ou des correspondances de payload. Les appels sortants sont validés et plafonnés pour éviter les cibles dangereuses et les boucles incontrôlées.

TYPES DE DÉCLENCHEUR

  • Webhook : schéma JSON fixe avec en-têtes de signature HMAC-SHA256. Choisissez ceci lorsque le récepteur attend le format KEEPitALIVE.
  • HTTP Request : méthode, en-têtes et modèle de corps entièrement personnalisés avec variables de substitution. Choisissez ceci pour des intégrations sur mesure.
  • Notify : envoie une notification via vos canaux d’alerte configurés (E-mail, Discord, Slack, etc.) avec un modèle de titre/corps personnalisé.
  • Incident : ouvre un incident de panne/dégradation lorsqu’une condition de payload correspond, puis le résout automatiquement lorsqu’un événement ultérieur efface la condition (ou lorsque vous désactivez/supprimez le déclencheur). Une source totalement silencieuse ne se résout pas automatiquement - voir Conditions.
Section des bases du déclencheur avec les quatre types : Webhook, HTTP Request, Notification et Incident
Choisissez d’abord le type - c’est lui qui décide de ce que fait le déclencheur lorsqu’il se déclenche.

ÉVÉNEMENTS

Neuf événements : down, recovered, degraded, flapping_start, flapping_stop, maintenance_start, maintenance_end, signal et payload. signal se déclenche pour les battements heartbeat du Récepteur d’événements. payload se déclenche pour les vérifications ayant capturé un payload de réponse, en particulier les moniteurs API.

Section des événements du déclencheur avec les modes Changement de statut et Chaque payload, et des cases pour tombe en panne, se rétablit, se dégrade, commence à osciller et cesse d’osciller
Changement de statut ne se déclenche qu’aux transitions. Chaque payload se déclenche à chaque vérification, ce qu’il vous faut pour les moniteurs récepteurs d’événements.

VARIABLES DE MODÈLE

Utilisez-les dans les modèles de corps/en-têtes/URL de HTTP Request et de titre de Notify :

Variables 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}})

Remarque : monitor.id et monitor.ref se résolvent tous deux à la référence publique du moniteur - jamais à un id de base de données interne. Basez vos systèmes en aval sur celle-ci.

Modèle de corps 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}}"
}

CONDITIONS

Les déclencheurs peuvent conditionner le déclenchement avec une expression sur le payload de vérification stocké. Grammaire : ==, !=, >, <, >=, <=, contains, exists, and, or, not, parenthèses, chemins pointés. Exemple : payload.failed_jobs > 0 and payload.status == "error". Les déclencheurs d’incident exigent une condition. Ils ouvrent l’incident tant que l’expression correspond et le résolvent lorsque l’expression cesse de correspondre. Comment fonctionne la résolution : l’incident se résout automatiquement lorsqu’une vérification ou un payload ultérieur réévalue le même déclencheur et que l’expression est désormais fausse. Il se ferme aussi immédiatement si vous désactivez ou supprimez le déclencheur. Important : le silence n’est pas un rétablissement. Si la source cesse totalement d’envoyer des payloads/heartbeats, aucun événement n’efface la condition, donc l’incident reste ouvert jusqu’à l’arrivée d’un nouvel événement ou une résolution manuelle. C’est intentionnel - nous ne considérons jamais « aucune donnée » comme « rétabli », car pour une source payload/signal le silence peut être la véritable panne.

Section des conditions du déclencheur avec une expression filtrant sur payload.failed_jobs et payload.status
Les conditions lisent le payload avec des chemins pointés simples - sans accolades ici, contrairement aux modèles de corps.
Ce que contient le payload, selon le type de moniteur
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.
Condition d’automatisation d’incident
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.

FORMAT DU PAYLOAD WEBHOOK

Les déclencheurs webhook envoient ce corps JSON fixe par POST. Basez votre gestionnaire sur event_id (déduplication) et monitor.ref (identité) :

Corps du 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"
}

VÉRIFICATION DE SIGNATURE (WEBHOOK)

Lorsqu’un déclencheur webhook a un secret, chaque livraison porte X-Timestamp et X-Signature-256. Recalculez et comparez pour rejeter les appels falsifiés :

Vérifier (pseudocode)
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

SÉMANTIQUE DE LIVRAISON

  • Idempotence : X-KEEPitALIVE-Event-ID (également event_id dans le corps / {{event.id}}) est généré une fois par déclenchement et réutilisé lors des nouvelles tentatives. Dédupliquez dessus pour qu’une nouvelle tentative arrivant après un premier essai lent ne soit pas traitée deux fois.
  • Politique de nouvelle tentative : les déclencheurs réseau peuvent réessayer 0-3 fois avec un délai de 5-600 secondes. Les déclencheurs Notify ne réessaient pas pour éviter les notifications visibles en double.
  • Les redirections ne sont PAS suivies : une réponse 3xx compte comme un échec de livraison. Pointez l’URL vers la destination finale.
  • Coupe-boucle : les livraisons sortantes portent X-KEEPitALIVE-Depth. Un battement renvoyé vers un récepteur d’événements propage depth+1, et les déclencheurs réseau cessent de se déclencher à la profondeur 3 - ainsi les chaînes déclencheur -> récepteur d’événements sont plafonnées à 3 sauts.

RECETTES D’INTÉGRATION

n8n / Make / Zapier : créez un Webhook (n8n) ou un catch hook Custom Webhook (Make/Zapier), collez son URL dans un déclencheur HTTP Request ou Webhook. Pour les déclencheurs Webhook, vérifiez X-Signature-256 dans une étape Function/Code avant d’agir ; branchez selon {{event.type}} et dédupliquez sur event_id.

Purge du cache Cloudflare (déclencheur 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 Home Assistant (déclencheur 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 générique « redémarrer le service »
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.

SÉCURITÉ

  • Le disjoncteur désactive un déclencheur après 10 échecs consécutifs (le propriétaire reçoit une notification dans l’app).
  • Politique de battement : la même règle 4-en-10-min s’applique par déclencheur.
  • Les déclencheurs Notify enregistrent un résultat de livraison par canal (livré / partiel / échoué) dans le journal d’exécution.
  • Le secret du webhook est affiché une fois lors de la création/rotation ; il est masqué dans toutes les réponses suivantes.
SuivantPages de statut