Domů / Docs

Dokumentace

Jak DiffMon funguje v oblasti monitoringu, alertů, bezpečnosti a API integrace.

Webhooks (HMAC, retrye, idempotence)

Posílejte DiffMon eventy do svých systémů s at-least-once delivery, HMAC podpisy, rotací secretů, retryi a redelivery.

Webhooks

Webhooky DiffMonu doručují change eventy do vašich systémů (CI, incident routing, audit, automation). Doručení jsou at-least-once, takže receiveři musí být idempotentní.

Klíčová slova: webhook retries, HMAC signature, idempotency, event deliveries, secret rotation, redelivery, change detection automation.

Semantika doručení

  • Method: POST (pouze HTTPS)
  • Content-Type: application/json
  • Delivery model: at-least-once
  • Idempotency key: X-Diffmon-Event-Id (je také uvnitř JSON envelope jako eventId)
  • Success: jakákoli odpověď 2xx
  • Retry: odpovědi mimo 2xx a síťové chyby

Retry schedule (v1)

DiffMon retryuje neúspěšná doručení podle kontraktního harmonogramu s malým jitterem:

  • okamžitě
  • +60 s
  • +300 s (5 min)
  • +1800 s (30 min)
  • potom +1800 s s jitterem až do maximálního počtu pokusů

Tento harmonogram má přežít přechodné výpadky, aniž by spamoval váš receiver.

Formát payloadu

DiffMon posílá stabilní envelope s metadaty eventu a objektem data, který obsahuje samotný payload eventu.

Běžná top-level pole envelope:

  • schemaVersion ("v1")
  • eventVersion (1)
  • eventId (unikátní identifikátor eventu)
  • eventType (například diff.detected)
  • occurredAt (ISO timestamp)
  • deliveredAt (ISO timestamp)
  • monitorId / diffId / snapshotId (nullable identifikátory)
  • data (event-specific payload)

DiffMon ve výchozím stavu nepřikládá do webhook payloadů multi-megabajtová body. Pro before/after snapshoty použijte artifact linky, pokud to plán a retention umožňují.

Typy eventů

DiffMon emituje různé typy eventů, aby zůstal signál čistý:

  • diff.detected - strukturované diffy pro JSON/HTML monitory
  • status.changed - přechody HTTP statusů (například 200 → 500) bez diffování error body
  • format.changed - přechody content-type (například očekává se JSON, ale přijde HTML)
  • monitor.failed - timeouty, DNS failure, TLS chyby a podobně

Tím se zabrání matoucím "obřím diffům", když endpoint vrátí error page nebo zcela selže.

Zabezpečení (HMAC podpisy)

Když má webhook endpoint nastavený secret, DiffMon každé doručení podepisuje.

Hlavičky

  • X-Diffmon-Timestamp: <unix_seconds>
  • X-Diffmon-Signature: v1=<hex_hmac_sha256>
  • Během grace period při rotaci secretu může DiffMon přidat také:
    • X-Diffmon-Signature-Old: v1=<hex_hmac_sha256>

Canonical string (v1)

Pro ověření podpisu spočítejte HMAC-SHA256 nad přesným raw request body:

Text
v1:<timestamp>:<rawBody>
  • <timestamp> je hodnota X-Diffmon-Timestamp
  • <rawBody> je raw JSON string přesně tak, jak přišel (nere-serializujte ho)

Doporučené kontroly receiveru:

  • odmítněte požadavky, pokud skew timestampu přesahuje ±300 sekund (ochrana proti replay)
  • podpisy porovnávejte constant-time způsobem

Pozastavení a redelivery

  • Endpointy můžete Pause, když potřebujete zastavit provoz během incidentu receiveru.
  • Pomocí Redeliver v UI znovu přehrajete konkrétní eventy po opravě receiveru.
  • DiffMon sleduje pokusy o doručení včetně status code, trvání a ukázek odpovědi pro snazší debugging.

Redirecty a SSRF ochrana

  • Webhook endpointy musí být na HTTPS.
  • DiffMon při sledování redirectů validuje cíle a blokuje nebezpečné destinace, aby zmírnil SSRF rizika.
  • Downgrade redirecty (HTTPS → HTTP) jsou blokované, pokud je explicitně nepovolíte.

Související dokumentace

  • Security - HTTPS enforcement, SSRF ochrana a bezpečné zacházení s redirecty.
  • Alerts and notifications - e-mail, routing a chování doručení.
  • Policy rules - post-diff suppression, přidání rout a escalation severity.
  • API monitoring - JSON monitoring, očekávání při parsování a format changes.
  • Smart Schema Validation - klasifikace schema vs value, severity a path-level diffy.
  • Versioning - stabilita kontraktu a politika breaking changes.
  • Audit log - pokusy o doručení, failure a provozní historie.
  • Deprecation - záruky životního cyklu webhooků a eventů.