Skip to main content

Events and webhooks

The current pilot implements a durable operational alert webhook for security-critical dependency degradation and recovery. Business-event subscriptions form a separate future contract.

Alerted components​

Alerts are generated for repeated failures and recovery of:

  • wallet or execution-adapter reconciliation; and
  • evidence-anchor delivery.

The transition is one of degraded, reminder, recovered, or test.

Payload​

{
  "schema_version": 1,
  "event_id": "<sha3-256 hex>",
  "source": "luvion-control-api",
  "component": "evidence_anchor",
  "transition": "degraded",
  "severity": "critical",
  "observed_at_unix_s": 1785040000,
  "consecutive_failures": 3,
  "message": "evidence_anchor reported 3 consecutive failures"
}

The payload deliberately excludes wallet addresses, assets, amounts, transaction hashes, credentials, keys, and raw internal errors.

Delivery guarantees​

  • Failures below the configured threshold do not alert.
  • Threshold crossing persists a pending event before network delivery.
  • Only HTTP 2xx marks an event delivered.
  • A failed delivery retains the same event ID across process restart.
  • Reminder events are rate limited.
  • Recovery produces one explicit event.
  • Redirects are disabled. Webhook URLs cannot contain embedded credentials, query parameters, or fragments.
  • HTTPS is required except for loopback-only testing.

Consumers should deduplicate on event_id, return 2xx only after durable acceptance, and avoid treating delivery order from unrelated components as a single global sequence.

Health endpoint​

When configured, /health reports independent objects for reconciler, evidence_anchor, and operational_alert. Fields include status, last success or attempt timestamps, consecutive failures, bounded last error, tracked or pending counts, and the pending alert event ID where applicable.

Use component health to decide whether intake, authorization, execution, or evidence publication should remain open. An HTTP process health response alone does not mean every security-critical dependency is healthy.

Current boundary​

The generic webhook and its recovery behavior are tested, but no partner-owned production destination or on-call process has been accepted. Request events such as approved, authorized, and executed are available through request state and evidence inspection; a stable outbound business-event webhook contract is not yet published.