CS-10217 trigger command on webhook event by richardhjtan · Pull Request #4098 · cardstack/boxel

richardhjtan · 2026-03-02T13:08:29Z

What is changing

Triggers a command when a webhook event is received, enabling automated workflows (e.g., creating a GithubEventCard for every GitHub PR/review/check event).
Introduce github event card def, this can be use as data source for submission card to query the events of a PR
Introduce process github event command to create github event card
Cover tests

Webhook command execution (realm-server)

handle-webhook-receiver.ts — After verifying the webhook signature, fetches matching webhook_commands rows from the DB, filters them against the incoming payload using pluggable filter handlers, and enqueues run-command jobs for each match. Falls back to the webhook-registering user if no realm owner is found.
webhook-filter-handlers.ts (new) — Introduces a WebhookFilterHandler interface with a registry pattern. Ships two handlers:
github-event — matches by X-GitHub-Event header; assembles { eventType, realm, payload } as command input.
default — pass-through; always matches and forwards the raw payload.

github-actions · 2026-03-02T13:16:10Z

Preview deployments

github-actions · 2026-03-02T13:29:34Z

Host Test Results

1 files ±0 1 suites ±0 1h 56m 13s ⏱️ +17s
1 922 tests ±0 1 907 ✅ ±0 15 💤 ±0 0 ❌ ±0
1 937 runs ±0 1 922 ✅ ±0 15 💤 ±0 0 ❌ ±0

Results for commit 3e3638b. ± Comparison against base commit 89f80bd.

♻️ This comment has been updated with latest results.

Copilot

Pull request overview

Adds webhook-triggered command execution (with GitHub-specific filtering) and introduces an “async incremental indexing” mode so card creation can return an assigned ID immediately without waiting for indexing—useful for command/worker-driven writes.

Changes:

Add webhook receiver support for looking up registered webhook commands, filtering by event payload/headers, and enqueueing run-command jobs.
Add X-Boxel-Async-Index / asyncIndex option to allow “fire-and-forget” incremental indexing and a 202 response that returns an ID immediately.
Expand realm session-room notification selection to include all users when a realm is world-readable.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
packages/runtime-common/realm.ts	Adds `asyncIndex` write option and 202 create-card response path to avoid blocking on indexing.
packages/runtime-common/db-queries/session-room-queries.ts	Adjusts session-room lookup query to include world-readable realm behavior.
packages/realm-server/handlers/handle-webhook-receiver.ts	Executes (enqueues) registered webhook commands after signature verification, using filter handlers.
packages/realm-server/handlers/webhook-filter-handlers.ts	Introduces pluggable webhook filter handlers (default + GitHub event filter).
packages/realm-server/tests/server-endpoints/webhook-receiver-test.ts	Adds/updates tests asserting webhook receipt and command enqueue behavior.
packages/realm-server/server.ts	Allows `X-Boxel-Async-Index` through CORS.
packages/matrix/scripts/register-github-webhook.ts	Adds a script to register an incoming GitHub webhook and associated webhook commands.
packages/host/app/services/store.ts	Adds async-index persistence path to obtain server-assigned IDs immediately in render/command contexts.
packages/catalog-realm/github-event/github-event.gts	Adds a card type to store GitHub webhook event payloads and derived fields.
packages/catalog-realm/commands/process-github-event.gts	Adds a command that saves a `GithubEventCard` from a webhook event.
packages/catalog-realm/commands/create-submission.ts	Adds an import related to card error handling (currently unused).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-02T13:31:36Z

packages/runtime-common/realm.ts

+    if (!options?.asyncIndex) {
+      await this.indexing();
+    }


asyncIndex skips await this.indexing(), but RealmIndexUpdater.update() overwrites #indexingDeferred (see runtime-common/realm-index-updater.ts), so calling update() while a from-scratch index is running can clobber the deferred and leave prior callers waiting on indexing() hanging. Consider still awaiting any in-progress indexing before scheduling the incremental update (even in async mode), or change RealmIndexUpdater to chain/de-dupe indexing promises instead of overwriting the single deferred.

packages/runtime-common/realm.ts

packages/realm-server/handlers/handle-webhook-receiver.ts

packages/matrix/scripts/register-github-webhook.ts

packages/catalog-realm/commands/create-submission.ts

packages/realm-server/handlers/webhook-filter-handlers.ts

packages/host/app/services/store.ts

packages/catalog-realm/commands/process-github-event.gts

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/realm-server/tests/server-endpoints/webhook-receiver-test.ts

Copilot · 2026-03-02T14:36:54Z

packages/matrix/scripts/register-github-webhook.ts

+  // Step 3: Register commands for both pull_request and pull_request_review events.
+  // Two separate commands are needed because GitHub uses different event headers
+  // for PR state changes vs. review submissions.
+  console.log('Setting up webhook commands...');
+
+  const baseFilter: Record<string, unknown> = {
+    type: 'github-event',
+  };
+
+  const eventTypes = [
+    'pull_request',
+    'pull_request_review',
+    'pull_request_review_comment',
+    'check_run',
+    'commit_comment',
+    'discussion_comment',
+  ];
+  for (let eventType of eventTypes) {
+    const cmd = await ensureWebhookCommand(jwt, {
+      incomingWebhookId: webhook.id,
+      command: commandURL,
+      filter: { eventType, ...baseFilter },
+    });
+    console.log(`  ✓ ${eventType.padEnd(22)} → command ${cmd.id}`);


The script registers github-event webhook-command filters that include type and eventType but omit submissionRealmUrl. In this PR’s GithubEventFilterHandler.buildCommandInput, missing submissionRealmUrl throws, so these commands would never be enqueued when events arrive. Either add submissionRealmUrl to the filter in this script, or adjust the handler to derive it when absent.

packages/realm-server/tests/async-index-test.ts

Copilot · 2026-03-02T14:36:54Z

packages/realm-server/handlers/webhook-filter-handlers.ts

+class GithubEventFilterHandler implements WebhookFilterHandler {
+  matches(
+    headers: Koa.Context['req']['headers'],
+    filter: Record<string, any>,
+  ): boolean {
+    let eventType = headers['x-github-event'] as string | undefined;
+
+    if (filter.eventType && filter.eventType !== eventType) {
+      return false;
+    }
+
+    return true;
+  }


GithubEventFilterHandler.matches has an incompatible parameter list and is called as matches(payload, headers, filter) by the receiver. As written it will treat the payload object as headers, so header-based filtering will behave incorrectly at runtime. Update the method signature to accept (payload, headers, filter) and implement the documented filtering (e.g. prNumber) using the parsed payload.

packages/realm-server/handlers/webhook-filter-handlers.ts

packages/realm-server/handlers/handle-webhook-receiver.ts

Copilot · 2026-03-02T14:36:55Z

packages/host/app/services/store.ts

+          isNew;
+        if (useAsyncIndex) {
+          // POST with X-Boxel-Async-Index: realm writes the file and returns
+          // 202 with the assigned card ID immediately (fire-and-forget index).


The comment says the async-index POST returns 202, but Realm.createCard returns 201 for async-index responses. Please update the comment to match the actual status code to avoid confusion for future maintainers.

Suggested change

// 202 with the assigned card ID immediately (fire-and-forget index).

// 201 with the assigned card ID immediately (fire-and-forget index).

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: df1db1a87d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/realm-server/handlers/handle-webhook-receiver.ts

chatgpt-codex-connector · 2026-03-02T14:48:50Z

packages/realm-server/handlers/webhook-filter-handlers.ts

+    if (filter.eventType && filter.eventType !== eventType) {
+      return false;
+    }
+
+    return true;


Enforce PR-number matching in github-event filters

GithubEventFilterHandler.matches only compares eventType and always returns true otherwise, so a filter that includes prNumber does not constrain execution to that PR. In practice, commands configured for a single PR will still run for all pull-request events of the same type (when submissionRealmUrl is present), which mixes unrelated PR events and triggers unintended command runs.

Useful? React with 👍 / 👎.

habdelra · 2026-03-02T17:43:25Z

from your description:

realm.ts — Supports a new X-Boxel-Async-Index: true request header on card POST. When set, the realm writes the file to disk and persists file meta, then returns 201 with the assigned card ID immediately. Indexing runs fire-and-forget in the background. This prevents a deadlock where the run-command worker job can't pick up the incremental-index job it enqueues.

store.ts — Uses the async-index path when creating new cards inside the headless Chrome render context (or when asyncIndex option is explicitly set). Calls setId() on the card instance with the server-assigned ID so downstream commands can reference it.

are we still doing this?

richardhjtan · 2026-03-03T02:23:44Z

@habdelra planning to remove it as we shall try increasing the worker approach in local from the office hour discussion

tintinthong · 2026-03-03T03:16:16Z

packages/base/commands/search-card-result.gts

+  static [queryableValue](_value: any, _stack: BaseDef[]): null {
+    return null;
+  }


do we need this?

It will have this error initially before adding this

tintinthong · 2026-03-03T03:16:53Z

packages/catalog-realm/commands/process-github-event.gts

+
+class ProcessGithubEventInput extends CardDef {
+  @field eventType = contains(StringField); // from command_filter
+  @field submissionRealmUrl = contains(StringField); // from command_filter


only one submssion realm right? field not needed. Do we need that?

or maybe if its a write. It shud just b called realm

tintinthong

Think we want to move all the async index stuff out of this PR

tintinthong · 2026-03-03T03:17:08Z

packages/catalog-realm/commands/process-github-event.gts

+
+class ProcessGithubEventInput extends CardDef {
+  @field eventType = contains(StringField); // from command_filter
+  @field submissionRealmUrl = contains(StringField); // from command_filter


or maybe if its a write. It shud just b called realm

tintinthong · 2026-03-03T03:18:22Z

packages/host/app/services/store.ts

+      // New cards still need a server-assigned ID in render context so that
+      // downstream commands can reference them. Use async-index so the realm
+      // returns the ID immediately without waiting for indexing to complete.
+      if (!instance.id && !opts?.doNotPersist) {
+        return (await this.persistAndUpdate(instance, {
+          realm: opts?.realm,
+          localDir: opts?.localDir,
+          asyncIndex: true,
+        })) as T | CardErrorJSONAPI;
+      }
+      // Existing cards: skip saves in render context (no auto-save).


do we need this portion of code?

Not needed because is part of async index work, will take it out

tintinthong · 2026-03-03T03:21:10Z

packages/runtime-common/db-queries/session-room-queries.ts

@@ -55,12 +63,23 @@ export async function fetchRealmSessionRooms(
  let rows = await query(dbAdapter, [


why was this fetchSessionRooms changed ahh?

@tintinthong Before that, users with read access from the public realm (eg: db permission record like catalog/submission realm with * all users) will not get a notification when a new card is created

The obvious scenario is when in the code mode file tree, the webhook is triggered and the command creates a card - the user will not see the latest file added in the LHS under the submission realm. The user has to refresh to see the latest file result

when running github event command experience timeout and file list is not updating in submission realm

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3e3638b462

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-04T09:40:35Z

packages/realm-server/handlers/webhook-filter-handlers.ts

+    if (!realm) {
+      throw new Error(
+        'realm must be provided in the filter for github-event webhook commands',


Reject github-event filters that omit realm

github-event filters without realm are currently accepted at creation time, but buildCommandInput throws when such a command actually matches, and handle-webhook-receiver catches that error and silently skips execution. This creates a latent misconfiguration where webhook deliveries return 200 but the command never runs for matching events; either validate realm up front or make the runtime fallback path actually work.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-04T09:40:35Z

packages/realm-server/handlers/handle-webhook-receiver.ts

+    try {
+      payload = JSON.parse(rawBody);
+    } catch (_error) {
+      console.warn('Failed to parse webhook payload for filtering');
+    }


Preserve non-JSON webhook payloads for command input

When the body is not valid JSON, the receiver logs a warning and keeps payload as {}, then still proceeds to enqueue commands. For generic/default webhook commands this drops the original payload entirely, so downstream commands cannot inspect the real webhook body and may make incorrect decisions. The handler should either pass through the raw body or fail the delivery for handlers that require structured JSON.

Useful? React with 👍 / 👎.

tintinthong · 2026-03-04T13:56:11Z

packages/catalog-realm/github-event/github-event.gts

+import NumberField from 'https://cardstack.com/base/number';
+import { JsonField } from 'https://cardstack.com/base/commands/search-card-result';
+
+export class GithubEventCard extends CardDef {


is there any value in subclassing this.

Might not be for now. If we found more different event cards involved, we can refactor the base event card which has similar attributes

richardhjtan requested a review from Copilot March 2, 2026 13:10

Copilot started reviewing on behalf of richardhjtan March 2, 2026 13:11 View session

Copilot AI reviewed Mar 2, 2026

View reviewed changes

richardhjtan requested a review from Copilot March 2, 2026 14:15

Copilot started reviewing on behalf of richardhjtan March 2, 2026 14:16 View session

Copilot AI reviewed Mar 2, 2026

View reviewed changes

richardhjtan force-pushed the CS-10217-trigger-command-on-webhook-event-2 branch from d44fccd to 08f2eba Compare March 2, 2026 14:38

richardhjtan mentioned this pull request Mar 2, 2026

Cs 10217 trigger command on webhook event #4074

Closed

richardhjtan force-pushed the CS-10217-trigger-command-on-webhook-event-2 branch from 08f2eba to df1db1a Compare March 2, 2026 14:43

richardhjtan requested review from a team, habdelra and lukemelia March 2, 2026 14:43

richardhjtan marked this pull request as ready for review March 2, 2026 14:43

chatgpt-codex-connector bot reviewed Mar 2, 2026

View reviewed changes

richardhjtan marked this pull request as draft March 2, 2026 15:41

tintinthong reviewed Mar 3, 2026

View reviewed changes

richardhjtan force-pushed the CS-10217-trigger-command-on-webhook-event-2 branch from 6764b98 to 60edaf6 Compare March 3, 2026 09:51

richardhjtan added 7 commits March 4, 2026 15:44

Register webhook and script in create PR command

c67a1ea

Trigger a command to create webhook event card

278d06c

Clean up register webhook script

6c3fb2c

Clean up register webhook script

a99259a

Address headless chrome and file indexing issue

76abf97

when running github event command experience timeout and file list is not updating in submission realm

Fix lint and clean up

9b82c4f

Fix lint

b9f5ae4

richardhjtan and others added 4 commits March 4, 2026 15:44

Fix deadlock when creating cards from headless Chrome command runner

200fffd

Comments for webhook

cf5b34b

Comment and tests

aaad020

Remove async index feature

65a6584

richardhjtan force-pushed the CS-10217-trigger-command-on-webhook-event-2 branch 2 times, most recently from 9b4feff to 91058a1 Compare March 4, 2026 08:41

Fix event not trigger and comment

3e3638b

richardhjtan force-pushed the CS-10217-trigger-command-on-webhook-event-2 branch from 91058a1 to 3e3638b Compare March 4, 2026 08:52

richardhjtan marked this pull request as ready for review March 4, 2026 09:34

richardhjtan requested a review from tintinthong March 4, 2026 09:34

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

tintinthong approved these changes Mar 4, 2026

View reviewed changes

tintinthong reviewed Mar 4, 2026

View reviewed changes

richardhjtan merged commit ce521ed into main Mar 4, 2026
105 checks passed

	// 202 with the assigned card ID immediately (fire-and-forget index).
	// 201 with the assigned card ID immediately (fire-and-forget index).

		@@ -55,12 +63,23 @@ export async function fetchRealmSessionRooms(
		let rows = await query(dbAdapter, [

Conversation

richardhjtan commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is changing

Uh oh!

github-actions bot commented Mar 2, 2026

Preview deployments

Uh oh!

github-actions bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Host Test Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

habdelra commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

richardhjtan commented Mar 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tintinthong left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richardhjtan commented Mar 2, 2026 •

edited

Loading

github-actions bot commented Mar 2, 2026 •

edited

Loading

habdelra commented Mar 2, 2026 •

edited

Loading