Vord

Enhancement Proposal

Proposal: Webhooks and event subscriptions

Integrators need to react to identity events in their own systems, and operators need to stream the audit trail to a SIEM. The identity event stream (ADR-0022) is already the substrate; this exposes it outward as a projection of that stream — no new architecture.

Motivation

Provisioning, lifecycle, security, and login events (user created/updated/deprovisioned, login, MFA enrolled, risk events) are useful to downstream systems. Today they live only inside Vord. Webhooks and SIEM streaming are developer- and operator-platform table-stakes.

Design

  • Subscriptions (per tenant, via the admin API, ADR-0021) to event types from the identity event stream (ADR-0022).
  • Webhook delivery: signed (HMAC/asymmetric, so the receiver verifies authenticity), retried with backoff, at-least-once with idempotency keys, and dead-lettered on persistent failure. Egress is allowlisted (SSRF, §12.5); payloads are redacted of secrets/PII beyond the subscription's scope (the canonical no-secrets rule is proposal 0004's; this applies it to payloads).
  • SIEM / log streaming as a sibling delivery mode (Splunk / Datadog / object-store sinks) over the same subscription model — the audit trail (ADR-0022) streamed out.
  • It is a consumer/projection of the ADR-0022 identity event stream — per the revised extensibility model (ADR-0029), webhooks are a delivery projection of that stream, not a parallel event mechanism; ordering and replay remain the stream's (ADR-0022), so a subscriber can resume from a cursor.

Alternatives considered

  • Polling an events API as the primary mechanism — rejected (latency, inefficiency); offered as a fallback for receivers that cannot accept webhooks.
  • Direct database access to the event store — rejected (couples integrators to internals).

Graduation criteria

A tenant subscribes to event types and receives signed, retried, idempotent webhooks; failures dead-letter and are replayable from a cursor; a SIEM stream delivers the audit trail.

Backward compatibility

A projection of the event stream (ADR-0022); no architecture change.

Open questions

  • Per-event-type payload schemas and their versioning.
  • Delivery-guarantee vs ordering trade-offs per subscription.