Start / Docs

Dokumentation

Wie DiffMon bei Monitoring, Alerts, Sicherheit und API-Integration funktioniert.

Webhooks (HMAC, Retries, Idempotenz)

Senden Sie DiffMon-Events mit At-least-once-Delivery, HMAC-Signaturen, Secret-Rotation, Retries und Redelivery in Ihre Systeme.

Webhooks

DiffMon-Webhooks liefern Change Events in Ihre Systeme (CI, Incident Routing, Audit, Automation). Deliveries sind at-least-once, daher müssen Receiver idempotent sein.

Schlüsselwörter: webhook retries, HMAC signature, idempotency, event deliveries, secret rotation, redelivery, change detection automation.

Delivery-Semantik

  • Method: POST (nur HTTPS)
  • Content-Type: application/json
  • Delivery model: at-least-once
  • Idempotency key: X-Diffmon-Event-Id (steht zusätzlich im JSON-Envelope als eventId)
  • Success: jede 2xx-Antwort
  • Retry: Antworten außerhalb von 2xx und Netzwerkfehler

Retry Schedule (v1)

DiffMon wiederholt fehlgeschlagene Deliveries nach einem vertraglichen Zeitplan mit leichtem Jitter:

  • sofort
  • +60 s
  • +300 s (5 min)
  • +1800 s (30 min)
  • danach +1800 s mit Jitter bis zur maximalen Anzahl an Versuchen

Dieser Zeitplan soll transiente Ausfälle überstehen, ohne Ihren Receiver zu spammen.

Payload-Format

DiffMon sendet einen stabilen Envelope mit Event-Metadaten und einem data-Objekt für den eigentlichen Event-Payload.

Typische Top-Level-Felder des Envelope:

  • schemaVersion ("v1")
  • eventVersion (1)
  • eventId (eindeutiger Event-Identifier)
  • eventType (zum Beispiel diff.detected)
  • occurredAt (ISO-Timestamp)
  • deliveredAt (ISO-Timestamp)
  • monitorId / diffId / snapshotId (nullable Identifier)
  • data (event-spezifischer Payload)

DiffMon legt standardmäßig keine mehrmegabytegroßen Bodies in Webhook-Payloads ab. Verwenden Sie Artifact-Links, wenn Plan und Retention Before-/After-Snapshots erlauben.

Event-Typen

DiffMon emittiert verschiedene Event-Typen, um das Signal sauber zu halten:

  • diff.detected - strukturierte Diffs für JSON-/HTML-Monitore
  • status.changed - HTTP-Statuswechsel (zum Beispiel 200 → 500) ohne Diffing von Error-Bodies
  • format.changed - Content-Type-Wechsel (zum Beispiel JSON erwartet, HTML erhalten)
  • monitor.failed - Timeouts, DNS-Fehler, TLS-Fehler und Ähnliches

So vermeiden Sie verwirrende "riesige Diffs", wenn ein Endpoint eine Error Page zurückgibt oder komplett fehlschlägt.

Sicherheit (HMAC-Signaturen)

Wenn für einen Webhook-Endpoint ein Secret gesetzt ist, signiert DiffMon jede Delivery.

  • X-Diffmon-Timestamp: <unix_seconds>
  • X-Diffmon-Signature: v1=<hex_hmac_sha256>
  • Während der Secret-Rotation-Grace-Phase kann DiffMon zusätzlich senden:
    • X-Diffmon-Signature-Old: v1=<hex_hmac_sha256>

Canonical String (v1)

Zur Verifikation der Signatur berechnen Sie HMAC-SHA256 über den exakten Raw Request Body:

Text
v1:<timestamp>:<rawBody>
  • <timestamp> ist der Wert von X-Diffmon-Timestamp
  • <rawBody> ist der Raw-JSON-String genau so, wie er empfangen wurde (nicht neu serialisieren)

Empfohlene Receiver-Prüfungen:

  • Anfrage ablehnen, wenn der Timestamp-Drift mehr als ±300 Sekunden beträgt (Replay-Schutz)
  • Signaturen mit Constant-Time-Vergleich prüfen

Pausieren und Redelivery

  • Sie können Endpoints auf Pause setzen, um Traffic während eines Receiver-Incidents zu stoppen.
  • Über Redeliver in der UI lassen sich einzelne Events erneut zustellen, nachdem Sie den Receiver repariert haben.
  • DiffMon protokolliert Delivery-Versuche inklusive Statuscodes, Dauer und Response-Snippets zur einfacheren Fehlersuche.

Redirects und SSRF-Schutz

  • Webhook-Endpoints müssen HTTPS verwenden.
  • DiffMon validiert Ziele und blockiert unsichere Destinationen, um SSRF-Risiken beim Folgen von Redirects zu reduzieren.
  • Downgrade-Redirects (HTTPS → HTTP) werden blockiert, sofern sie nicht explizit erlaubt sind.

Zugehörige Dokumentation

  • Security - HTTPS Enforcement, SSRF-Schutz und sicherer Umgang mit Redirects.
  • Alerts and notifications - E-Mail, Routing und Delivery-Verhalten.
  • Policy rules - Post-Diff-Suppression, zusätzliche Routen und Severity-Eskalation.
  • API monitoring - JSON-Monitoring, Parsing-Erwartungen und Format Changes.
  • Smart Schema Validation - Schema-vs-Value-Klassifikation, Severity und Path-Level-Diffs.
  • Versioning - Vertragsstabilität und Breaking-Change-Policy.
  • Audit log - Delivery-Versuche, Failures und Betriebshistorie.
  • Deprecation - Garantien für den Lebenszyklus von Webhooks und Events.