spec(governance-admin): v0.1.25.33 — webhook lifecycle EventTypes + per-row event emission

amavashev · amavashev · commit df71b461b7b0 · 2026-04-23T07:44:09.000-04:00
Closes the v0.1.25.32 deferral that explicitly carved out webhooks from
the bulk-action Event emission contract because no `webhook.*` lifecycle
EventTypes existed. This revision adds the EventTypes and wires per-row
Event emission through `bulkActionWebhooks`, the three single-op webhook
operations, and the dispatcher's auto-disable transition.

Changes to `cycles-governance-admin-v0.1.25.yaml`:

- EventType enum: six new values under a new "Webhook lifecycle" group
  between the tenant and api_key blocks —
  webhook.created / webhook.updated / webhook.paused / webhook.resumed /
  webhook.disabled / webhook.deleted. Naming follows the
  tenant.suspended / tenant.reactivated precedent: each event name
  mirrors the resulting status, rather than the v0.1.25.32 note's
  provisional webhook.enabled / webhook.disabled pairing which would
  have conflated operator PAUSE with dispatcher auto-DISABLE.
  webhook.disabled is now reserved exclusively for the health-driven
  transition.

- New schema EventDataWebhookLifecycle — mirrors EventDataTenantLifecycle;
  carries subscription_id, tenant_id, previous_status, new_status,
  changed_fields, disable_reason.

- bulkActionWebhooks: added EVENTS block documenting the per-row
  emission contract (PAUSE → webhook.paused, RESUME → webhook.resumed,
  DELETE → webhook.deleted), skipped/failed rows produce no Event,
  correlation_id = webhook_bulk_action:&lt;action&gt;:&lt;request_id&gt;.
  bulkActionWebhooks explicitly never emits webhook.disabled.

- createWebhookSubscription / updateWebhookSubscription /
  deleteWebhookSubscription: EVENTS blocks documenting the single-op
  emission contract and correlation_id patterns. updateWebhookSubscription
  disambiguates status-change PATCH (emits webhook.paused/resumed) from
  pure property-change PATCH (emits webhook.updated). No-op PATCH emits
  nothing.

- WebhookSubscription.FAILURE HANDLING: documents that the dispatcher
  MUST emit webhook.disabled on auto-transition with
  correlation_id = webhook_auto_disable:&lt;subscription_id&gt;:&lt;failure_batch_id&gt;
  and populate disable_reason. Emission happens in the dispatcher
  component, not the admin API.

- info.version 0.1.25.32 → 0.1.25.33; info.summary trailer extended.

Also prepends a v0.1.25.33 changelog entry (Keep-a-Changelog) and
regenerates merged/cycles-openapi-admin-merged.yaml.

Additive-only: new enum values (existing clients MUST ignore
unrecognized values per the EventType extensibility note), new optional
schema, new prose sections. No removals, no renames, no wire-breaking
changes. Reference servers compile against the regenerated model
without code changes; a follow-up cycles-server-admin patch release
will wire the emits into WebhookAdminController and the dispatcher's
auto-disable path.

The existing cascade variant webhook.disabled_via_tenant_cascade is
unchanged — the tenant-close cascade retains its v0.1.25.29 Rule 1
identity (tenant_close_cascade:&lt;tenant_id&gt;:&lt;request_id&gt;) and is
distinct from the new standalone webhook.disabled event.
diff --git a/changelogs/cycles-governance-admin.md b/changelogs/cycles-governance-admin.md
@@ -6,6 +6,90 @@ New entries are added directly to this file. See `scripts/validate_changelogs.py
 
 ---
 
+## v0.1.25.33 — 2026-04-23
+
+- Adds webhook lifecycle EventTypes and documents per-row Event
+  emission on `bulkActionWebhooks`, the three single-op webhook
+  operations (`createWebhookSubscription`, `updateWebhookSubscription`,
+  `deleteWebhookSubscription`), and the dispatcher's auto-disable
+  transition. Closes the v0.1.25.32 deferral, which explicitly carved
+  out webhooks because no `webhook.*` lifecycle EventTypes existed.
+
+  New EventType enum values (six):
+
+  * `webhook.created`  — new subscription provisioned
+  * `webhook.updated`  — subscription properties modified (url,
+    event_types, etc.) with no status change
+  * `webhook.paused`   — subscription status ACTIVE → PAUSED (operator)
+  * `webhook.resumed`  — subscription status PAUSED → ACTIVE (operator,
+    or DISABLED → ACTIVE when operator re-enables a dispatcher-disabled
+    subscription)
+  * `webhook.disabled` — subscription status → DISABLED (auto, after
+    failure threshold; never produced by the admin API)
+  * `webhook.deleted`  — subscription record removed
+
+  Naming follows the `tenant.suspended` / `tenant.reactivated`
+  precedent — each event name mirrors the resulting status. This
+  intentionally diverges from the v0.1.25.32 note's provisional
+  `webhook.enabled` / `webhook.disabled` pairing: webhook status has
+  three values (ACTIVE / PAUSED / DISABLED), and conflating a user
+  PAUSE with the dispatcher's auto-DISABLE under one event name would
+  hide a meaningful operational distinction. `webhook.disabled` is
+  now reserved exclusively for the health-driven transition.
+
+  `bulkActionWebhooks` — server MUST emit one Event per
+  successfully-mutated row:
+
+  * PAUSE  → `webhook.paused`
+  * RESUME → `webhook.resumed`
+  * DELETE → `webhook.deleted`
+
+  Skipped and failed rows MUST NOT produce an Event. Emission is
+  bound to actual state transition, matching the single-op contract.
+
+  Correlation identity for bulk: `webhook_bulk_action:<action>:<request_id>`
+  (mirrors `tenant_bulk_action:...` / `budget_bulk_action:...` from
+  v0.1.25.32).
+
+  Single-op endpoints — correlation identities:
+
+  * `createWebhookSubscription` → `webhook_create:<subscription_id>`
+  * `updateWebhookSubscription` → `webhook_update:<subscription_id>:<request_id>`
+  * `deleteWebhookSubscription` → `webhook_delete:<subscription_id>`
+
+  Dispatcher auto-disable — when `consecutive_failures` exceeds
+  `disable_after_failures` and status flips to DISABLED, the
+  dispatcher MUST emit `webhook.disabled` with correlation_id
+  `webhook_auto_disable:<subscription_id>:<failure_batch_id>` and
+  populate `disable_reason` in the payload
+  (e.g. `consecutive_failures_exceeded_threshold`). Documented
+  under `WebhookSubscription.FAILURE HANDLING`; emission happens in
+  the dispatcher component, not the admin API.
+
+  New payload schema: `EventDataWebhookLifecycle` (mirrors
+  `EventDataTenantLifecycle`) carrying `subscription_id`, `tenant_id`,
+  `previous_status`, `new_status`, `changed_fields`, and
+  `disable_reason`. `previous_status` is omitted on `webhook.created`;
+  `new_status` is omitted on `webhook.deleted`; `changed_fields` is
+  populated only on `webhook.updated`; `disable_reason` is populated
+  only on `webhook.disabled`.
+
+  The existing cascade variant
+  `webhook.disabled_via_tenant_cascade` (referenced in the tenant
+  close cascade prose) is unchanged — the cascade path retains its
+  v0.1.25.29 Rule 1 identity
+  `tenant_close_cascade:<tenant_id>:<request_id>` and is distinct from
+  the new standalone `webhook.disabled` event.
+
+  Additive-only spec change: six new EventType enum values (existing
+  clients MUST ignore unrecognized values per the EventType
+  extensibility note at line 1575), one new schema, new prose sections
+  on four operations plus FAILURE HANDLING. No removals, no renames,
+  no wire-incompatible changes. Reference servers continue to compile
+  against the regenerated model without code changes; a follow-up
+  cycles-server-admin patch release will wire the emits into
+  `WebhookAdminController` and the dispatcher's auto-disable path.
+
 ## v0.1.25.32 — 2026-04-22
 
 - Editorial: adds normative `EVENTS` sections to `bulkActionBudgets`
diff --git a/cycles-governance-admin-v0.1.25.yaml b/cycles-governance-admin-v0.1.25.yaml
@@ -1,18 +1,24 @@
 openapi: 3.1.0
 info:
   title: Complete Budget Governance Admin API
-  version: 0.1.25.32
+  version: 0.1.25.33
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0
   summary: >-
-    Stable governance base — document revision 0.1.25.32; semantic base
+    Stable governance base — document revision 0.1.25.33; semantic base
     frozen at 0.1.25.9. This file is self-sufficient for the current
     v0.1.25 conformance target (runcycles' reference servers implement
     this today — adds a normative tenant-close cascade contract at
     document revision 0.1.25.31; document revision 0.1.25.32 adds
     per-row Event emission requirements to bulkActionBudgets and
-    bulkActionTenants for observability parity with single-op paths)
+    bulkActionTenants for observability parity with single-op paths;
+    document revision 0.1.25.33 introduces webhook lifecycle EventTypes
+    — webhook.created / webhook.updated / webhook.paused /
+    webhook.resumed / webhook.disabled / webhook.deleted — and wires
+    per-row Event emission into bulkActionWebhooks, the single-op
+    create / update / delete webhook operations, and the dispatcher's
+    auto-disable path, closing the v0.1.25.32 deferral)
     and also serves as the base for the upcoming v0.1.26
     spec family. Covers tenant management, authentication, and runtime
     enforcement. NOTE: This file alone is NOT sufficient for the
@@ -1612,6 +1618,14 @@ components:
         - tenant.closed                 # Tenant status → CLOSED (irreversible)
         - tenant.settings_changed       # Default overage policy, TTL, or overdraft limit changed
 
+        # --- Webhook lifecycle events (document revision 0.1.25.33) ---
+        - webhook.created               # New subscription provisioned
+        - webhook.updated               # Subscription properties modified (url, event_types, etc.) with no status change
+        - webhook.paused                # Subscription status ACTIVE → PAUSED (operator action)
+        - webhook.resumed               # Subscription status PAUSED → ACTIVE (operator action)
+        - webhook.disabled              # Subscription status → DISABLED (auto, after failure threshold)
+        - webhook.deleted               # Subscription record removed
+
         # --- API key events ---
         - api_key.created               # New API key provisioned
         - api_key.revoked               # Key revoked (manual or automated)
@@ -2101,6 +2115,47 @@ components:
             List of fields that were modified (e.g., ["name", "default_commit_overage_policy"]).
             Empty for create events.
 
+    EventDataWebhookLifecycle:
+      type: object
+      description: >-
+        Payload for webhook.created, webhook.updated, webhook.paused,
+        webhook.resumed, webhook.disabled, webhook.deleted events
+        (document revision 0.1.25.33). Mirrors EventDataTenantLifecycle
+        in shape — carries the subscription identity, the status
+        transition, and the fields modified (for update events).
+      properties:
+        subscription_id:
+          type: string
+          description: Subscription identifier (e.g., "whsub_01abc...").
+        tenant_id:
+          type: string
+          description: >-
+            Tenant owning the subscription. Use "__system__" for
+            system-wide subscriptions.
+        previous_status:
+          type: string
+          enum: [ACTIVE, PAUSED, DISABLED]
+          description: >-
+            Status before the transition. Omitted on webhook.created.
+        new_status:
+          type: string
+          enum: [ACTIVE, PAUSED, DISABLED]
+          description: >-
+            Status after the transition. Omitted on webhook.deleted.
+        changed_fields:
+          type: array
+          items:
+            type: string
+          description: >-
+            Fields modified (e.g., ["url", "event_types"]). Populated on
+            webhook.updated; empty on create, pause, resume, disable,
+            and delete events.
+        disable_reason:
+          type: string
+          description: >-
+            Only set on webhook.disabled. Human-readable reason
+            (e.g., "consecutive_failures_exceeded_threshold").
+
     EventDataApiKey:
       type: object
       description: >-
@@ -2192,7 +2247,14 @@ components:
         - On non-2xx response: retry with exponential backoff (1s, 2s, 4s, ... up to max_retries).
         - After max_retries exhausted: mark delivery as FAILED, emit system.webhook_delivery_failed event.
         - After consecutive_failures exceeds disable_after_failures: status → DISABLED automatically.
-        - Disabled subscriptions can be re-enabled via PATCH.
+          The dispatcher MUST emit one `webhook.disabled` Event on this
+          auto-transition (document revision 0.1.25.33). Payload conforms
+          to EventDataWebhookLifecycle with `previous_status` = ACTIVE
+          or PAUSED, `new_status` = DISABLED, and `disable_reason`
+          populated (e.g., "consecutive_failures_exceeded_threshold").
+          correlation_id = `webhook_auto_disable:<subscription_id>:<failure_batch_id>`.
+        - Disabled subscriptions can be re-enabled via PATCH — that path
+          emits `webhook.resumed` (see updateWebhookSubscription).
       required: [subscription_id, tenant_id, url, event_types, status, created_at]
       additionalProperties: false
       properties:
@@ -5955,6 +6017,12 @@ paths:
         - Omit tenant_id to create a system-wide subscription (receives events from all tenants).
         - System-wide subscriptions still respect scope_filter if provided.
 
+        EVENTS (document revision 0.1.25.33):
+        - On success, server MUST emit one `webhook.created` Event.
+          Payload conforms to EventDataWebhookLifecycle with
+          `new_status` = ACTIVE and `previous_status` omitted.
+          correlation_id = `webhook_create:<subscription_id>`.
+
         AUTHORIZATION:
         - Requires admin key (X-Admin-API-Key)
       security:
@@ -6185,6 +6253,27 @@ paths:
         - Pause delivery: set status to PAUSED
         - Rotate signing secret: provide new signing_secret value
         - Change event types: provide new event_types array (replaces, does not merge)
+
+        EVENTS (document revision 0.1.25.33):
+        - On every successful PATCH the server MUST emit exactly one
+          Event, typed by the nature of the change:
+            * Status unchanged, any other field(s) mutated →
+              `webhook.updated`. `changed_fields` lists the mutated
+              field names.
+            * Status ACTIVE → PAUSED → `webhook.paused`.
+            * Status PAUSED → ACTIVE → `webhook.resumed`.
+            * Status DISABLED → ACTIVE (operator re-enable) →
+              `webhook.resumed`.
+          When a single PATCH both changes status AND mutates other
+          fields, the server emits the status-typed event
+          (`webhook.paused` / `webhook.resumed`) and `changed_fields`
+          lists the non-status mutations for operator visibility.
+          A no-op PATCH (zero fields mutated) MUST NOT emit an Event.
+        - Payload conforms to EventDataWebhookLifecycle.
+          correlation_id = `webhook_update:<subscription_id>:<request_id>`.
+        - Auto-disable after failure threshold produces
+          `webhook.disabled` via the dispatcher, not via this PATCH
+          path. See WebhookSubscription.FAILURE HANDLING.
       security:
         - AdminKeyAuth: []
       parameters:
@@ -6254,6 +6343,13 @@ paths:
       description: >-
         Permanently removes the subscription. Pending deliveries are cancelled.
         This operation is irreversible.
+
+        EVENTS (document revision 0.1.25.33):
+        - On success, server MUST emit one `webhook.deleted` Event.
+          Payload conforms to EventDataWebhookLifecycle with
+          `previous_status` set to the subscription's status at time
+          of deletion and `new_status` omitted.
+          correlation_id = `webhook_delete:<subscription_id>`.
       security:
         - AdminKeyAuth: []
       parameters:
@@ -6820,6 +6916,35 @@ paths:
         - Overall HTTP 200 even when some rows fail; response envelope
           reports success/failure counts.
 
+        EVENTS (document revision 0.1.25.33):
+        - Server MUST emit one Event per successfully-mutated row,
+          typed by action: PAUSE → `webhook.paused`,
+          RESUME → `webhook.resumed`, DELETE → `webhook.deleted`.
+          Skipped rows (ALREADY_IN_TARGET_STATE, MISSING) and failed
+          rows MUST NOT produce an Event — emission is bound to actual
+          state transition, matching the single-op
+          createWebhookSubscription / updateWebhookSubscription /
+          deleteWebhookSubscription contract.
+        - Each emitted Event carries
+          `correlation_id = webhook_bulk_action:<action>:<request_id>`
+          (action lowercased, e.g.
+          `webhook_bulk_action:pause:req_abc`). Operators retrieve the
+          full bulk fan-out via
+          GET /v1/admin/events?correlation_id=…; the shared request_id
+          also ties every emitted row to the invocation's single
+          AuditLogEntry.
+        - Event payload conforms to EventDataWebhookLifecycle.
+        - `webhook.disabled` is NOT produced by bulkActionWebhooks —
+          that EventType is reserved for the auto-health-driven
+          transition described in
+          WebhookSubscription.FAILURE HANDLING. Operator PAUSE actions
+          always emit `webhook.paused` regardless of prior status.
+
+        AUDIT LOG:
+        - One AuditLogEntry per bulk-action invocation (not per row).
+          Per-row Events (above) are the operator-visible audit trail;
+          the AuditLogEntry is the compliance-facing invocation record.
+
         AUTHORIZATION:
         - AdminKeyAuth only.
       security:
diff --git a/merged/cycles-openapi-admin-merged.yaml b/merged/cycles-openapi-admin-merged.yaml
