Event webhooks

Status

The webhook surface is planned for Phase 5 of the platform roadmap, alongside the language SDKs and the MCP server. This page documents the intended event set and payload shape so that subscribers — repository systems, CRIS integrations, mirror sites — can plan against a stable contract.

Until webhooks ship, the practical alternative is to poll /wp-json/casrai/v1/dictionary/stats on the REST endpoints and react when last_modified or release change. The response is small and cached at the edge, so a five-minute poll is cheap.

Events

Three event types are planned for the initial release. The set is deliberately small; new events will only be added in response to a documented integration need.

• dictionary.release.published — fires when a new dictionary release (for example v2026.2) is tagged and made the default served version. Subscribers typically use this to invalidate caches and trigger a re-pull.
• dictionary.term.updated — fires when an existing term's definition, examples, counter-examples, aliases, or relationships change. The event carries the term slug and a small diff summary; subscribers fetch the full term via GraphQL or REST if they need the new content.
• dictionary.term.deprecated — fires when a term transitions to deprecated status. The payload includes any supersededBy pointer so consumers can update internal references in a single pass.

Payload shape

All event payloads share a common envelope. The envelope identifies the event, names the dictionary release in force, and timestamps the event in UTC. The data property carries the event-specific body.

{
  "id":         "evt_01HX...",
  "event":      "dictionary.release.published",
  "occurred_at":"2026-06-01T09:00:00Z",
  "release":    "v2026.2",
  "data": {
    "release":         "v2026.2",
    "previous_release":"v2026.1",
    "release_notes_url":"https://casrai.org/dictionary/release-notes/v2026.2",
    "terms_added":     42,
    "terms_updated":   118,
    "terms_deprecated": 6
  }
}

{
  "id":         "evt_01HX...",
  "event":      "dictionary.term.updated",
  "occurred_at":"2026-05-17T13:42:11Z",
  "release":    "v2026.1",
  "data": {
    "slug":         "genai-disclosure",
    "canonical_uri":"https://casrai.org/dictionary/genai-disclosure",
    "changed_fields":["definition_operational","examples"],
    "previous_version":"v2026.1-rev3",
    "new_version":     "v2026.1-rev4"
  }
}

{
  "id":         "evt_01HX...",
  "event":      "dictionary.term.deprecated",
  "occurred_at":"2026-05-17T13:50:02Z",
  "release":    "v2026.1",
  "data": {
    "slug":           "legacy-funder-id",
    "canonical_uri":  "https://casrai.org/dictionary/legacy-funder-id",
    "superseded_by":  "funder-identifier",
    "deprecation_url":"https://casrai.org/dictionary/legacy-funder-id#deprecation-notice"
  }
}

Delivery and verification

Events will be POSTed as application/json to the subscriber's configured URL. Each request will carry an X-Casrai-Signature header containing an HMAC-SHA256 over the raw body, keyed on a secret issued at subscription time. Subscribers verify by recomputing the HMAC and constant-time-comparing.

import crypto from "node:crypto";

export function verifyCasraiSignature(rawBody, headerValue, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(headerValue, "hex");

  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Failed deliveries (non-2xx responses or timeouts) will be retried with exponential back-off for 24 hours, after which the event is moved to a dead-letter queue surfaced in the subscriber's admin view. Subscribers must therefore treat handlers as idempotent and key off the envelope id to deduplicate.

Subscription management

Subscriptions will be created and revoked through the same authenticated REST surface documented on the REST endpoints page, using Application Password authentication. A subscription declares one or more event types, a delivery URL, and an optional release filter for consumers only interested in stable releases.

Related

• REST endpoints — including the /dictionary/stats probe used in the polling fallback.
• API changelog — for breaking changes to the webhook contract.
• Language SDKs — Phase 5 sibling work.
• External: the OAuth 2.0 Bearer Token (RFC 6750) specification, used for subscription-management calls.