Home / Docs

Documentation

How DiffMon works across monitoring, alerts, security, and API integration.

Webhooks (HMAC, retries, idempotency)

Send Diffmon events to your systems with at-least-once delivery, HMAC signatures, secret rotation, retries, and redelivery.

Webhooks

Diffmon webhooks deliver change events to your systems (CI, incident routing, auditing, automation). Deliveries are at-least-once, so receivers must be idempotent.

Keywords: webhook retries, HMAC signature, idempotency, event deliveries, secret rotation, redelivery, change detection automation.

Delivery semantics

  • Method: POST (HTTPS only)
  • Content-Type: application/json
  • Delivery model: at-least-once
  • Idempotency key: X-Diffmon-Event-Id (also present inside the JSON envelope as eventId)
  • Success: any 2xx response
  • Retry: non-2xx responses and network errors

Retry schedule (v1)

Diffmon retries failed deliveries using a contract schedule with small jitter:

  • immediate
  • +60s
  • +300s (5m)
  • +1800s (30m)
  • then +1800s with jitter until max attempts

This schedule is designed to survive transient outages without spamming your receiver.

Payload format

Diffmon sends a stable envelope with event metadata and a data object containing the event payload.

Common top-level envelope fields:

  • schemaVersion ("v1")
  • eventVersion (1)
  • eventId (unique event identifier)
  • eventType (e.g. diff.detected)
  • occurredAt (ISO timestamp)
  • deliveredAt (ISO timestamp)
  • monitorId / diffId / snapshotId (nullable identifiers)
  • data (event-specific payload)

Diffmon does not include multi-megabyte bodies in webhook payloads by default. Use artifact links (when enabled by plan/retention) to fetch before/after snapshots.

Event types

Diffmon emits different event types to keep signal high:

  • diff.detected — structured diffs for JSON/HTML monitors
  • status.changed — HTTP status transitions (e.g. 200 → 500) without diffing error bodies
  • format.changed — content-type transitions (e.g. expected JSON but received HTML)
  • monitor.failed — timeouts, DNS failures, TLS errors, etc.

This prevents confusing “giant diffs” when an endpoint returns an error page or fails.

Security (HMAC signatures)

When a webhook endpoint has a secret configured, Diffmon signs each delivery.

Headers

  • X-Diffmon-Timestamp: <unix_seconds>
  • X-Diffmon-Signature: v1=<hex_hmac_sha256>
  • During secret rotation grace periods, Diffmon may also include:
    • X-Diffmon-Signature-Old: v1=<hex_hmac_sha256>

Canonical string (v1)

To verify the signature, compute HMAC-SHA256 over the exact raw request body: v1::

  • <timestamp> is the value of X-Diffmon-Timestamp
  • <rawBody> is the raw JSON string exactly as received (do not re-serialize)

Recommended receiver checks:

  • Reject if timestamp skew exceeds ±300 seconds (replay protection)
  • Constant-time compare signatures

Pausing and redelivery

  • Pause endpoints to stop traffic during receiver incidents.
  • Redeliver from the UI to replay specific events after you fix your receiver.
  • Diffmon tracks delivery attempts (status codes, durations, and response snippets) to help debugging.

Redirect and SSRF protections

  • Webhook endpoints must be HTTPS.
  • Diffmon validates targets and blocks unsafe destinations to mitigate SSRF when following redirects.
  • Downgrade redirects (HTTPS → HTTP) are blocked unless explicitly allowed.
  • Security - HTTPS enforcement, SSRF protections, and safe redirect handling.
  • Alerts and notifications - email, routing, and delivery behavior.
  • Policy rules - post-diff suppression, route additions, and severity escalation.
  • API monitoring - JSON monitoring, parsing expectations, and format changes.
  • Smart schema validation - schema vs value classification, severity, and path-level diffs.
  • Versioning - contract stability and breaking change policy.
  • Audit log - delivery attempts, failures, and operational history.
  • Deprecation - webhook/event lifecycle guarantees.