ENG-1490: webhook event docs

[Yan Xue (yanxue06)]

Summary

Documentation for the ENG-1490 webhook event work. Covers the dynamic envelope ({ event, platform, ...payload }) and the six iMessage event types now produced by the webhook.

Companion to spectrum-webhook#4. (The originally-planned spectrum-ts changes were reverted in favor of a webhook-only design.)

Three commits

1. Dynamic envelope — describe WebhookEventEnvelope, note the messages arm is byte-identical to the prior contract, drop the stale "read receipts/typing/reactions coming soon" line in delivery.mdx.
2. iMessage event reference — per-event payload tables for readReceipt, chatRead, messageEdit, messageUnsend, reactionRemoved, groupChange. Documents platform-specific quirks (text-only edits, tapback → emoji mapping, participantLeft having no actor, etc.).
3. Reframe forward-compat — soften "providers declare events automatically" to "the webhook gains new producers." Customer-facing wire format is unchanged.

Test plan

• bun run docs:generate builds the rendered .mdx without errors.
• Code blocks pass the docs type-check.
• Review prose once the webhook PR is reviewed and merged.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 68645487-9987-4675-b14e-8d7daed48a46

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch eng-1490-webhook-events

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🤖 Merged latest origin/main into this branch and resolved the conflicts.

Conflicts found (2 files):

1. docs-src/webhooks/events.mdx.vel — two conflicts, both resolved in favor of this PR's content:

   • Body shape type: kept the PR's generic WebhookEventEnvelope ({ event: string; platform?: string; ... }) over main's WebhookEventPayload union that hard-coded messages as the only event. The whole point of this PR is the multi-event model (messages + the six iMessage events), so main's "messages is the only event today" framing is superseded.
   • event: "messages" intro: kept the PR's "canonical inbound-message arm … on-wire shape is frozen" wording over main's "this is the only event currently emitted." Main's accuracy-pass note about reactions/typing/edits arriving via content.type is preserved in the Content shapes section; the contradictory "only event" claim was dropped.

2. webhooks/delivery.mdx — "What we don't deliver" bullet, resolved in favor of this PR:

   • Kept the PR's "Typing indicators. Not exposed by any provider today." Main's bullet ("standalone reaction/typing/edit events aren't separate events … read receipts aren't delivered in any form yet") is now factually superseded — this PR documents readReceipt, messageEdit, and reactionRemoved as first-class events, so keeping main's text would make the page contradict the new event reference.

Verification: pnpm install --frozen-lockfile, pnpm lint, and pnpm typecheck:docs all pass. (webhooks/events.mdx is a gitignored build output, so no generated file needed committing; webhooks/delivery.mdx is hand-maintained with no .vel source.)

[github-actions]

Resolved merge conflicts with main (merge-base was #69's accuracy pass; main has since landed #70 webhooks-events-cleanup, #71 webhooks-inbound-arm-accuracy, and the "only content arms delivered inbound" commit).

Two conflicts, both in hand-authored content (no lockfile/generated-file conflicts):

1. docs-src/webhooks/events.mdx.vel — the event: "messages" payload intro.

• This PR: "This is the canonical inbound-message arm … Its on-wire shape is frozen."
• main: "This is the only event currently emitted … A reaction is not a separate event — it arrives inside this messages payload as a content.type arm."

2. webhooks/delivery.mdx — the "What we don't deliver" list.

• This PR: "Typing indicators. Not exposed by any provider today."
• main: "Standalone reaction events. … Typing indicators, edits, poll votes, and read receipts aren't delivered in any form yet."

Resolution: kept this PR's version on both. Rationale: the two sides encode contradictory models. This PR's entire purpose is documenting six standalone iMessage events (readReceipt, chatRead, messageEdit, messageUnsend, reactionRemoved, groupChange). main's wording asserts the opposite — that messages is the only event and that edits/read-receipts "aren't delivered in any form." Taking main's text would directly contradict the new ## iMessage events section this PR adds, so I preferred the PR content to keep the document internally consistent.

I verified the auto-merged regions stay coherent with the six-events model: reactions added still ride the messages stream as a reaction content arm (kept from main's accuracy pass), while reactionRemoved is a standalone event — the PR already documents that asymmetry, so nothing was lost from main's reaction guidance.

⚠️ Needs a human product decision before merge: this is a genuine factual disagreement, not just wording. main's recent accuracy passes claim messages is the only event; this PR claims six iMessage events ship as of spectrum-ts 1.10 (installed dep is spectrum-ts 1.11.3). Please confirm the SDK actually emits these six top-level events before merging — if main's view is correct, this PR's premise needs revisiting rather than a conflict resolution.

Verified after resolution: pnpm install --frozen-lockfile, pnpm lint, and pnpm typecheck:docs all pass.