Webhook-Payload-Referenz

Ein Webhook-Benachrichtigungskanal stellt jeden Alarm, jede Entwarnung, jede Erinnerung und jede Warnung eines Kunden an einen HTTP-Endpoint zu, den du kontrollierst. Diese Seite beschreibt die Nutzlast des generischen Webhook-Kanals: den JSON-Body, die Request-Header und die Signaturprüfung.

Der Request

Ein Endpoint, der wiederholt nicht einmal eine Verbindung annimmt, bekommt pro Versuch ein kürzeres Zeitlimit. Die Zustellung wird dadurch nicht eingestellt, nur der Preis eines scheiternden Versuchs sinkt.

Request-Header

Eigene Header, die am Kanal konfiguriert sind, werden ergänzt und stechen die Vorgaben.

Signatur prüfen

Hinterlegst du am Kanal ein Secret, signieren wir die exakten Bytes des Request-Bodys mit HMAC-SHA256 und schicken das Ergebnis hex-kodiert in X-Webhook-Signature. Prüfe gegen den rohen Body, bevor du ihn parst und neu serialisierst, sonst kippt der Vergleich schon an einem Leerzeichen.

import crypto from 'node:crypto'

function isValidSignature(rawBody, headerValue, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected, 'utf8')
  const b = Buffer.from(String(headerValue ?? ''), 'utf8')
  // Längenprüfung zuerst: timingSafeEqual wirft bei ungleicher Länge.
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Nutzlast

{
  "type": "alert",
  "check_degraded": false,
  "incident_id": 8094,
  "message": "Website Acme Shop is DOWN",
  "expected_response_error": null,
  "ssl": null,
  "website": {
    "id": 10597,
    "name": "Acme Shop",
    "url": "https://shop.example.com",
    "custom_fields": {}
  },
  "customer": {
    "id": 42,
    "name": "Acme GmbH",
    "email": "ops@example.com",
    "custom_fields": {}
  },
  "incident": {
    "type": "http_status",
    "started_at": "19.08.2026, 17:32:04",
    "resolved_at": "N/A",
    "status": "open",
    "ssl": null,
    "error_details": {
      "check_degraded": false,
      "status_code": 503,
      "error_message": "Unexpected status code (503) (expected: 200)",
      "expected_response_error": null,
      "response_time_ms": 412,
      "blocking_response": {
        "status_code": 503,
        "vendor": "Cloudflare",
        "headers": {
          "server": "cloudflare",
          "cf-ray": "a2daec8259183caa-CDG"
        }
      }
    },
    "locations": ["de-fra", "fi-hel", "pl-waw"],
    "screenshot": null,
    "screenshot_url": "https://…",
    "diagnostics": null
  }
}

Felder auf oberster Ebene

incident

incident.error_details

incident.type

http_status, downtime (wird als down ausgeliefert), response_time, https_redirect, keyword_check, page_size, ssl_handshake, ssl_expiry, ssl_warning, domain_expiry, domain_expiry_warning, dns.

Bei einem Dienst-Monitor wird downtime stattdessen als Protokoll ausgeliefert: icmp, smtp, ssh, ftp oder imap-pop.

blocking_response: wer die Anfrage abgewiesen hat

Ein 403, 406, 429 oder 503 sagt, dass etwas die Anfrage abgelehnt hat. Es sagt nicht, ob deine Seite aus ist oder ob eine Web Application Firewall unsere Prüfung aussortiert hat, bevor sie deinen Server erreichte. Trägt die Antwort Header, die den Absender benennen, reichen wir sie in diesem Feld durch. Bei jedem anderen Status ist es null, ebenso wenn die Antwort niemanden benannt hat.

Die aufgezeichneten Header sind eine feste Liste: server, via, retry-after, x-cache, x-served-by, cf-ray, cf-cache-status, cf-mitigated, x-sucuri-id, x-sucuri-block, x-iinfo, x-cdn, x-akamai-transformed, akamai-grn, x-amz-cf-id, x-amz-cf-pop, x-datadome, x-request-id, x-waf-event-id, cdn-pullzone, cdn-requestid. Cookies sowie Anmeldeheader werden nie aufgezeichnet und nie versendet, und jeder Wert wird bei 200 Zeichen gekappt.

Damit lassen sich zwei Lagen unterscheiden, die am Statuscode allein gleich aussehen:

const blocked = payload.incident?.error_details?.blocking_response
if (blocked) {
  // Unsere Prüfung wurde am Rand abgewiesen, der Ursprung kann völlig gesund sein.
  notifyOps(`${blocked.vendor ?? 'Ein Edge'} hat die Prüfung mit ${blocked.status_code} abgewiesen`)
}

Bedingungen und Body-Templates

Ein Webhook-Kanal kann Bedingungen tragen, dann wird nur zugestellt, wenn die Nutzlast dazu passt, und ein eigenes JSON-Body-Template, dann ersetzt dein Template den oben beschriebenen Body. Beides stellst du am Kanal in der App ein.