fix(ai-mcp): accept MCP Events deliveries whose webhook-id differs from eventId #2150
main fromrefs/pull/2150/head·opened View on GitHubcreateMCPEventWebhook returns 400 for every event from a server that follows SEP-3415. The receiver requires the webhook-id header to equal the eventId in the body, but SEP-3415 says that webhook-id "MUST NOT be derived from eventId". This PR removes that check, so the receiver accepts both forms.
🎯 Changes#
packages/ai-mcp/src/events/webhook.ts: the receiver no longer compareswebhook-idwitheventId. The check on the eventnamestays.- Unit tests: one test for each
webhook-idform, and one test for one event on two subscriptions. - The shared test events server (
tests/helpers/events-server.ts) now sends a per-messagewebhook-idfor events. It already did this forgap,terminatedandverificationenvelopes. The client tests and the Playwrightmcp-events.spec.tsnow run with the SEP form. - E2E: the
testing/e2eapp records themessageIdthatonEventgets. The subscribe and emit test checks that thewebhook-idis amsg_id and that the event keeps its ownevt_eventId. - Changeset: patch for
@tanstack/ai-mcp.
No docs change. The docs already say to dedupe on (subscription.id, messageId), and messageId is the webhook-id. The docs do not say that webhook-id must equal eventId.
✅ Checklist#
- I have followed the steps in the Contributing guide.
- I have tested code changes locally with
pnpm run test:pr, or these tests do not apply to this pull request. - I fully understand the code in this pull request, including any code generated with AI assistance.
- Docs: I updated
docs/for this change, or this change is not user-facing. - Changeset: I added a changeset (
pnpm changeset), or this PR does not change a published package.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Root cause#
Issue. An app that uses createMCPEventWebhook drops every event from a server that sends a per-message webhook-id, as SEP-3415 requires. The receiver returns 400 at stage: 'envelope' with "Event does not match the subscription", and the server retries until it stops. gap, terminated and verification envelopes are not affected, because the receiver does not compare their webhook-id.
Cause. createMCPEventWebhook rejects an event when classified.event.eventId !== webhookId. #1816 added this check.
Fix. Remove the eventId part of the check. The signature still binds webhook-id to the body, because the HMAC covers webhook-id, the timestamp and the raw body. onEvent still gets the header as messageId.
SEP-3415 separates the two ids because one event can match two subscriptions on the same receiver. The event then arrives twice with the same eventId. With a per-message webhook-id, the documented dedupe key (subscription.id, messageId) keeps both deliveries.
Possible alternatives#
- An option to require the old form. For example
requireWebhookIdEqualsEventId. SEP-3415 forbids that form, so the option adds API that no caller needs. - Dedupe in the receiver. Store each
(subscription.id, webhook-id)and skip repeats. That is a new feature with a new store contract, and the docs already give dedupe to the app. It is out of scope for this fix.
Test plan#
Commands run, on Node 24.22 and pnpm 11.9.0:
pnpm test:pr: pass (8 affected projects), andscan-dangling-dtsis clean.pnpm exec vitest runinpackages/ai-mcp: 671 passed.pnpm exec playwright test tests/mcp-events.spec.tsintesting/e2e: 4 passed.- The same tests with the
webhook.tsfrommain: they fail, as below.
Before the fix (vitest run tests/events, with webhook.ts from main):
× accepts webhook-id a per-message id (SEP-3415)
× delivers one event to two subscriptions with different webhook-ids
× an emitted event reaches onEvent and advances the stored cursor
× delivers a signed event over the network to onEvent and stores the cursor
× retries a 503 from a throwing onEvent and delivers on the next attempt
AssertionError: expected 400 to be 204 // Object.is equality
Tests 5 failed | 153 passed (158)
2 failed
[chromium] › tests/mcp-events.spec.ts:19:3 › ... › subscribe → emit → received contains the event
[chromium] › tests/mcp-events.spec.ts:104:3 › ... › unsubscribe stops deliveries
2 passed
After the fix:
Tests 671 passed (671)
4 passed (10.8s)
Manual test:
- On
main, copytests/events/webhook.test.tsfrom this branch intopackages/ai-mcp. - Run
pnpm exec vitest run tests/events/webhook.test.tsinpackages/ai-mcp. The per-message test fails withexpected 400 to be 204. - On this branch, run the same command. All tests pass.
How this PR makes testing easy: the unit tests cover both forms, and the Playwright spec covers the per-message form. There is no new example app.
Risk / rollback#
Low. The receiver now accepts more deliveries, but each delivery still needs a valid signature, a fresh timestamp, a known subscription key and a matching event name. To roll back, revert this PR.
Posted by an AI agent with human oversight.
Summary by CodeRabbit#
- Bug Fixes
- Webhook event deliveries accept per-message IDs that differ from the event ID, while remaining compatible with older servers that use matching IDs.
- Event callbacks provide the message ID separately from the event ID, including when the same event is delivered to multiple subscriptions.
- 1
tanstack-source added labelsbug
No actionable comments were generated in the recent review.
Walkthrough
-
The MCP webhook receiver accepts
webhook-idvalues that differ from the event’seventId. The event-server helper generates a separate ID for each subscription delivery. Tests verify that message IDs and event IDs are reported separately.Changes: Webhook message ID handling
Layer / File(s) Summary Webhook ID acceptance
packages/ai-mcp/src/events/webhook.ts,packages/ai-mcp/tests/events/webhook.test.ts,.changeset/mcp-events-webhook-id-per-message.mdThe receiver no longer requires webhook-idto matcheventId; it still checks the event name. Tests cover matching and distinct IDs and confirm thatonEventreceives the message ID separately. The changeset documents the compatibility behavior and deduplication guidance.Subscription delivery IDs
packages/ai-mcp/tests/helpers/events-server.ts,packages/ai-mcp/tests/events/webhook.test.ts,testing/e2e/src/lib/mcp-events-session.ts,testing/e2e/src/routes/api.mcp-events-control.ts,testing/e2e/tests/mcp-events.spec.tsThe event-server helper generates a msg_ID for each subscription delivery and reuses it for retries. Tests cover one event delivered to two subscriptions with distinct message IDs. E2E session data and responses include message IDs, and the E2E test checks them separately from event IDs.Estimated code review effort: 2 (Simple) | ~10 minutes
Change: Bug fix
Suggested reviewers:
carlosziegler
Merge Risk:
Minimal · up toa32ff-
The webhook receiver now accepts per-message webhook IDs that differ from the event ID, and it still accepts the older form where they match. The behavior change is narrow and covered by tests. No merge-blocking risk is evident.
Pre-merge checks:
4-
Check name Status Explanation Title check The title names the main change: the receiver in @tanstack/ai-mcpno longer requires webhook-id to equal eventId, so MCP Events deliveries with per-message IDs are accepted. The title is specific, con…Description check The description follows the template. It has the Changes section, the full checklist, and the Release Impact section, with the changeset item checked. It also gives a clear root cause, fix, test plan … Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request. Full details: Title check
-
Explanation
The title names the main change: the receiver in
@tanstack/ai-mcpno longer requires webhook-id to equal eventId, so MCP Events deliveries with per-message IDs are accepted. The title is specific, concise, and matches the changeset, code change, and tests.
Full details: Description check
-
Explanation
The description follows the template. It has the Changes section, the full checklist, and the Release Impact section, with the changeset item checked. It also gives a clear root cause, fix, test plan with results, and risk/rollback. The Changes section is detailed. The docs item is checked, and the description says no docs change was needed, which is a minor mismatch with the checkbox wording but is explained.
-
Finishing Touches
-
Generate unit tests (beta)
-
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Recent review info-
Run configuration-
- Source mode: Auto
- Repository: TanStack/ai
- Branch: main
- File: .coderabbit.yaml
- Commit: 1888233
- Layers: Repository YAML
- Review profile: CHILL
- Plan: Advanced
- Run ID:
6bebec67-4cbb-418c-bb0b-552778c280b3
Commits-
Reviewing files that changed from the base of the PR and between 0ea2ccd4cfb63be316806e8a84113cbd60e01a5c and a32ffe89fa1de358f5f5cfb05cc61df1b8e9e53c.
Files selected for processing: 3-
testing/e2e/src/lib/mcp-events-session.tstesting/e2e/src/routes/api.mcp-events-control.tstesting/e2e/tests/mcp-events.spec.ts
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.
-
-
github-actions[bot](GitHub profile, opens in a new tab) assignedtombeckenham
Thanks for the PR, @leggetter! 🙌 @tombeckenham will take a look.
Automated pre-review checks
- ✅ CI passing
- ✅ No merge conflicts
- ✅ Changeset present
- ⚠️ No E2E test changes detected — behavior changes need coverage under
testing/e2e/(see CONTRIBUTING)
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer
This PR is useful. It lets
createMCPEventWebhookaccept awebhook-idthat differs fromeventId. Related work is #1816. This PR does not link an issue.TanStack Source bot, value agent
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: author
github-actions[bot](GitHub profile, opens in a new tab) removed labelswaiting-on: maintainer
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: a32ffe89fa1de358f5f5cfb05cc61df1b8e9e53c
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR