fix(webhooks): materialize stack-declared webhooks into the dispatcher (#3461)#3489
Merged
Conversation
#3461) The spec `WebhookSchema` authoring surface (`defineStack({ webhooks })` / `defineWebhook()`, `object` / `isActive`) was disconnected from the runtime dispatcher, which fans out off `sys_webhook` DATA rows (`object_name` / `active`) written only by hand through the object's CRUD UI. Nothing turned a declared webhook into a dispatchable row, so authoring `webhooks:` on a stack was a silent no-op (ADR-0078) — the showcase itself shipped one that did nothing. - `bootstrapDeclaredWebhooks` reads declared `webhook` metadata from the ObjectQL registry (where manifest decomposition already parks `stack.webhooks`), validates each through `WebhookSchema.parse()` (the spec schema finally gets a real consumer), and materializes it into a `sys_webhook` row: `object → object_name`, `isActive → active`, full envelope → `definition_json`. Runs on the DATA ENGINE alone, before the auto-enqueuer's first refresh — NOT gated behind the realtime/messaging dispatch prerequisites (else a realtime-less deployment reproduces the silent no-op). - Seed-not-clobber provenance (mirrors sys_sharing_rule #2909): `sys_webhook` gains `managed_by` / `customized`. Declared webhooks re-seed as `managed_by: 'package'`; a row an admin created (`admin`) or edited (`customized`, stamped by a beforeUpdate hook) is never overwritten. - showcase: require the `webhooks` + `realtime` capabilities (so the dispatcher actually mounts) and ship the demo webhook inactive (placeholder endpoint). - Fix the stale `SysWebhookDelivery` import in the i18n extract config (dead since delivery moved to service-messaging). Connector `webhooks` remain not-yet-enforced (#3197). Registering `webhook` as a metadata type + GOVERNED liveness enrollment is a tracked follow-up. Verified: 9 new unit tests (mapping / idempotency / seed-not-clobber / invalid / end-to-end dispatch), red-proofed; and a real showcase boot — declared webhook materializes into a sys_webhook row, same-DB reboot stays idempotent, and an admin's customized edit survives redeploy. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 104 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #3461.
Problem
The spec
WebhookSchemaauthoring surface was disconnected from the runtime dispatcher — not merely a naming drift. A webhook authored declaratively (defineStack({ webhooks })/defineWebhook(), declaringobject/isActive) is decomposed into the ObjectQL registry aswebhookmetadata, but the dispatcher (AutoEnqueuer) fans out offsys_webhookdata rows (object_name/active) that until now were only ever written by hand through the object's CRUD UI. No ingestion path turned a declared webhook into a dispatchable row, so authoringwebhooks:on a stack was a silent no-op (ADR-0078). The showcase app itself shipped awebhooks:entry that did nothing — and, separately, never required thewebhookscapability, so the dispatcher plugin wasn't even mounted.Per the issue's decision, this is Option A — build the bridge (Option B would retire a public authoring surface the showcase already uses).
What changed
bootstrap-declared-webhooks.ts— reads declaredwebhookmetadata from the registry (falling back to the metadata service), validates each throughWebhookSchema.parse()(the spec schema finally has a real consumer + default-fill), and materializes asys_webhookrow:object → object_name,isActive → active, full validated envelope →definition_json(whence the enqueuer reads headers/secret/timeout). Modeled on the siblingbootstrapDeclaredSharingRules.bootAutoEnqueue, which meant a realtime-less deployment silently failed to materialize — the very no-op class this closes. Caught during the real-boot dogfood.)sys_sharing_rule, Audit sibling declared-metadata↔record two-store types (sys_position, sys_sharing_rule, sys_capability) per ADR-0094 addendum #2909):sys_webhookgainsmanaged_by/customized. Declared webhooks re-seed every boot asmanaged_by: 'package'; a row an admin created (admin) or edited (customized, stamped by abeforeUpdatehook inwebhook-provenance.ts) is never overwritten — a deactivated noisy webhook survives redeploys.webhooks+realtimecapabilities so the dispatcher actually mounts, and ship the demo webhook inactive (thehooks.exampleURL is a placeholder; activate it in Setup).WebhookSchemadocstring documents the materialization contract. Connectorwebhooksremain not-yet-enforced (Audit: several event/subscription/connector enums are schema-only (declared, no runtime consumer) #3197).SysWebhookDeliveryimport in the i18n extract config (dead since delivery moved toservice-messaging).Verification
9 new unit tests (
bootstrap-declared-webhooks.test.ts) — mapping, idempotency, declared-change propagation, seed-not-clobber, admin-name-collision, invalid-webhook skip, no-op-when-empty, and end-to-end dispatch (declared → materialized →AutoEnqueuerfires with headers/secret fromdefinition_json). Red-proofed (breaking the mapping + the skip guard fails the right tests). Full suite: 23 passing.Real showcase boot (
objectstack dev, SQLite):sys_webhookrow —object_name=showcase_task,active=0,managed_by=package✅customizededit (active=1) survives redeploy despite the declaredisActive:false✅Build + DTS type-check green.
Follow-ups (out of scope)
webhookas a first-class metadata type + enroll it in the livenessGOVERNEDset (would have caught this automatically) — tracked.webhooksenforcement (Audit: several event/subscription/connector enums are schema-only (declared, no runtime consumer) #3197).sys_webhook_deliveryi18n blocks (pre-existing migration debt).🤖 Generated with Claude Code