Events & webhooks overview

1. The event feed is the source of truth. GET /api/v1/events is a durable, cursor-ordered pull feed of everything that happened in your organization (within your key’s scopes). Events are written in the same database transaction as the mutation that caused them, so the feed never misses a change.
2. Webhooks are lossy wakeups. A webhook delivery tells you that new events are available — never what happened. The payload is minimal by design; on receiving one (and on your own schedule) you poll the feed from your last cursor. Webhooks can be lost, replayed, or delayed without correctness consequences, and no sensitive data ever transits your endpoint.

​

The event envelope

{
  "id": "9f2b7c3e-0000-4000-8000-000000000000",
  "cursor": "123",
  "entity": "case",
  "entityId": "case-example-id",
  "eventType": "case.status_changed",
  "occurredAt": "2026-08-11T12:00:00Z",
  "actor": { "id": "key-or-user-id", "type": "service", "name": "Example CRM sync" },
  "payload": { "caseId": "case-example-id", "previousStatus": "…", "newStatus": "…" },
  "diff": null,
  "relatedIds": [{ "entity": "case", "id": "case-example-id" }],
  "correlationId": null,
  "metadata": { "origin": "…" }
}

• id is the dedup key: the feed is at-least-once, so treat events idempotently.
• cursor is strictly monotonic per organization. Pass the last cursor you processed as ?after= to resume.
• actor + metadata.origin support echo suppression: skip events your own integration caused by comparing actor.id to your key id.
• All payloads and diffs pass sensitive-field redaction before they reach the feed. Events marked ids-only in the catalog carry an empty payload — fetch details via the scoped resource endpoints.

​

Reading the feed

curl "https://attorney.dearlegal.com/api/v1/events?after=123&limit=200" \
  -H "x-api-key: YOUR_API_KEY"

​

Subscriptions

• POST /api/v1/webhook-subscriptions — { "url": "https://...", "eventTypes": [...] }. eventTypes accepts public event types and entity.* wildcards (e.g. case.*), validated against the public catalog; omitted, you receive the default wakeup.
• The subscription signing secret is returned once, on create — and again only when you rotate it (PATCH with "rotateSecret": true).
• The URL must be HTTPS on a host in your key’s webhook allowed hosts allowlist (configured on the key; fail-closed when empty).

​

Ordering & delivery guarantees

• Feed cursors are strictly monotonic per organization, and a later cursor never becomes readable before an earlier one.
• The feed is at-least-once — dedupe on envelope id.
• Event retention is currently indefinite, but do not build on unbounded replay; a retention window may be introduced with advance notice.