Document Standard Webhooks delivery - #128
Conversation
|
Important Review skippedNo new commits to review since the last review. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe webhook documentation now defines a Standard Webhooks contract, durable delivery and retries, endpoint management, raw-byte signature verification, secret rotation, and troubleshooting for the ChangesStandard Webhooks contract and operations
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant EventSource
participant EndpointFanout
participant WebhookHandler
participant DurableQueue
EventSource->>EndpointFanout: Emit message.received
EndpointFanout->>WebhookHandler: Send signed HTTPS POST
WebhookHandler->>WebhookHandler: Verify raw body and headers
WebhookHandler->>DurableQueue: Enqueue by webhook-id
DurableQueue-->>WebhookHandler: Confirm durable enqueue
WebhookHandler-->>EndpointFanout: Return 2xx
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
CodeRabbit (@coderabbitai) full review |
✅ Action performedFull review finished. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
webhooks/quickstart.mdx (1)
101-104: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDefine or annotate
enqueue.
enqueueis used at line 103 but never declared or imported. A reader who copiesserver.tsgets a runtime error. Add a minimal local definition or state in prose thatenqueueis your own queue write.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@webhooks/quickstart.mdx` around lines 101 - 104, Define or annotate enqueue in the quickstart example so readers understand it is an application-provided queue-write operation and copying server.ts does not leave an unresolved symbol. Add a minimal local definition near the existing enqueue call, or explicitly explain in prose that it must be implemented by the application.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@webhooks/quickstart.mdx`:
- Around line 107-114: Update the quickstart to align its documented runtime
with the implementation: either add the Node.js path using `@hono/node-server` and
serve({ port: 3000, fetch: app.fetch }) with corresponding Node.js install and
run commands, or revise the guide to explicitly support Bun only and remove
Node.js claims.
---
Nitpick comments:
In `@webhooks/quickstart.mdx`:
- Around line 101-104: Define or annotate enqueue in the quickstart example so
readers understand it is an application-provided queue-write operation and
copying server.ts does not leave an unresolved symbol. Add a minimal local
definition near the existing enqueue call, or explicitly explain in prose that
it must be implemented by the application.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c81b6a2a-d923-46a6-960e-7cd9c0d5b608
📒 Files selected for processing (7)
docs-src/webhooks/events.mdx.velwebhooks/delivery.mdxwebhooks/managing-webhooks.mdxwebhooks/overview.mdxwebhooks/quickstart.mdxwebhooks/troubleshooting.mdxwebhooks/verifying-signatures.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (2)
docs-src/**/*.mdx.vel
📄 CodeRabbit inference engine (CLAUDE.md)
docs-src/**/*.mdx.vel: Pull type information through vellum from.d.tsfiles instead of writing it by hand - usesym.signaturefor full declarations,sym.members[]for interface properties,sym.variants[]for enums/discriminated unions, andsym.doc.summaryfor descriptions
ImportTypeTooltipfrom/snippets/type-tooltip.mdxin every.mdx.velfile that mentions a type symbol in prose
Use<TypeTooltip>whenever a named type appears inline (method return type, parameter, passing reference), with one{% set %}per symbol at first reference and pairing the tooltip with a short prose description
Use<Accordion>for reference material like long options tables, enumerated values, and event-type mappings, with title being just the type name (no suffixes), description from{{ sym.doc.summary }}, and related accordions stacked in<AccordionGroup>
In Accordion tables containing TypeScript type text, apply the standard escape chain:replace("\n", " ") | replace(" ", "") | replace("|", "\\|") | replace("<", "<") | replace(">", ">")
Use<Tabs>component when showing the same task in multiple ways (e.g. plain text / with options / builder API), not successive###headings
Do not include type annotations in code block comments; move type information to prose with<TypeTooltip>instead
Avoid scare-quote comments in code blocks (e.g.// Narrowed,// Returns); explain in surrounding prose or delete
Keep code snippets minimal with real API calls and no mock data shaped to look real
Drive table rows from vellum when they map 1:1 to source members/variants using{% for %}loops; only hand-write tables when there's no corresponding symbol, when adding categorization/editorial structure, or for dynamic counts using{{ sym.variants | length }}
When vellum extracts well-formed patterns, use the extracted data; for fall-through cases (unions of named references, non-literal discriminators, mixed unions, pure literal unions), hand-write tables...
Files:
docs-src/webhooks/events.mdx.vel
**/*.mdx
📄 CodeRabbit inference engine (AGENTS.md)
**/*.mdx: Pages should be written as MDX files with YAML frontmatter
Use active voice and second person ("you") in documentation
Keep sentences concise with one idea per sentence in documentation
Use sentence case for headings in documentation
Bold UI elements in documentation (e.g., Click Settings)
Use code formatting for file names, commands, paths, and code references in documentation
Files:
webhooks/quickstart.mdxwebhooks/overview.mdxwebhooks/delivery.mdxwebhooks/verifying-signatures.mdxwebhooks/managing-webhooks.mdxwebhooks/troubleshooting.mdx
🧠 Learnings (1)
📚 Learning: 2026-05-27T07:01:01.271Z
Learnt from: yanxue06
Repo: photon-hq/docs PR: 56
File: docs-src/webhooks/events.mdx.vel:0-0
Timestamp: 2026-05-27T07:01:01.271Z
Learning: In Vellum-templated webhook docs where the data source is a Zod schema whose fields (e.g., iMessage `Space` `type`/`phone` from `spaceSchema`) are not exposed as enumerable members/variants to the TypeScript extractor, do not use Vellum `{% for %}` loops to generate rows. Instead, write the relevant table rows explicitly (e.g., hand-written rows inside the appropriate `<Accordion>` blocks) so the docs render the expected `type`/`phone` entries.
Applied to files:
docs-src/webhooks/events.mdx.vel
🪛 Betterleaks (1.7.3)
webhooks/quickstart.mdx
[high] 38-38: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
webhooks/delivery.mdx
[grammar] ~21-~21: Ensure spelling is correct
Context: ...ter verifying the signature and durably enqueueing the event. Run slow application work af...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
webhooks/troubleshooting.mdx
[style] ~19-~19: To form a complete sentence, be sure to include a subject.
Context: ...de message.received. - deliveryMode should be fusor for Standard Webhooks delive...
(MISSING_IT_THERE)
[style] ~70-~70: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...-Afterfor intentional backpressure. - Return503` for a temporary outage. - Return ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~71-~71: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... Return 503 for a temporary outage. - Return most other 4xx responses for permanen...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~72-~72: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sponses for permanent request errors. - Return 410 only to disable the endpoint. ##...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (15)
docs-src/webhooks/events.mdx.vel (4)
9-61: LGTM!
129-142: LGTM!
110-127: 🗄️ Data Integrity & IntegrationThe format is intentionally split:
X-Spectrum-Signatureuses thev0=header prefix, while the signed string usesv0:.webhooks/verifying-signatures.mdxdocuments both formats, so these pages are not inconsistent.> Likely an incorrect or invalid review comment.
63-102: 📐 Maintainability & Code QualityKeep the hand-written webhook tables.
The configured
spectrum-ts@12.0.0package does not expose a matching symbol for these fields. Its native webhook schema uses a differentevent/space/messageenvelope, so Vellum loops andTypeTooltipdo not apply here.> Likely an incorrect or invalid review comment.webhooks/overview.mdx (2)
62-95: LGTM!
41-58: 🎯 Functional CorrectnessKeep the
slackplatform value.The event reference lists
imessageand> Likely an incorrect or invalid review comment.webhooks/delivery.mdx (3)
6-53: LGTM!
55-92: LGTM!
109-110: 🗄️ Data Integrity & IntegrationKeep the
succeedresponse key.The API reference defines the envelope as
{ succeed, data }, and the webhook examples use the same key.> Likely an incorrect or invalid review comment.webhooks/troubleshooting.mdx (2)
6-45: LGTM!
53-107: LGTM!webhooks/managing-webhooks.mdx (2)
106-132: LGTM!Also applies to: 134-142, 144-154
87-89: 🗄️ Data Integrity & IntegrationNo changes needed. The four-day retry window and
delivery_failuresmapping matchwebhooks/delivery.mdx.webhooks/quickstart.mdx (1)
27-50: LGTM!Also applies to: 126-147
webhooks/verifying-signatures.mdx (1)
6-38: LGTM!Also applies to: 42-97, 99-134
|
CodeRabbit (@coderabbitai) review |
✅ Action performedReview finished.
|
|
CodeRabbit (@coderabbitai) review |
✅ Action performedReview finished.
|
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
webhooks/managing-webhooks.mdx (1)
74-74: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse active voice and second person for the downgrade rule.
Schema downgrades are not supported.is passive. Replace it withYou cannot downgrade an endpoint schema.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@webhooks/managing-webhooks.mdx` at line 74, Update the downgrade rule in the schema documentation to use active voice and address the reader directly: state that the user cannot downgrade an endpoint schema, replacing the passive wording while preserving the same meaning.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@webhooks/managing-webhooks.mdx`:
- Around line 64-69: Update the webhook PATCH curl example to stop passing
PROJECT_SECRET through the -u argument; use a protected --netrc-file or
equivalent credential source so the secret is not exposed in process arguments,
while preserving PROJECT_ID authentication and the request payload.
- Around line 23-24: Clarify in the webhook management example that its string
schemaVersion selects the management API endpoint payload contract, and is
distinct from the numeric schemaVersion in the raw event envelope documented in
webhooks/overview.mdx. Explicitly instruct readers not to send the envelope
value to the management API or compare the two fields.
In `@webhooks/troubleshooting.mdx`:
- Line 19: Update the Standard Webhooks troubleshooting checklist to reference
the endpoint’s public schema ID instead of using raw-inbound.v1. Document
raw-inbound.v1 only when describing the delivered envelope’s internal
schemaVersion, keeping these identifiers clearly separate.
---
Nitpick comments:
In `@webhooks/managing-webhooks.mdx`:
- Line 74: Update the downgrade rule in the schema documentation to use active
voice and address the reader directly: state that the user cannot downgrade an
endpoint schema, replacing the passive wording while preserving the same
meaning.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 30e6950d-8171-4e2b-a9c8-38902e7f730a
📒 Files selected for processing (5)
docs-src/webhooks/events.mdx.velwebhooks/managing-webhooks.mdxwebhooks/overview.mdxwebhooks/quickstart.mdxwebhooks/troubleshooting.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- docs-src/webhooks/events.mdx.vel
- webhooks/quickstart.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (1)
**/*.mdx
📄 CodeRabbit inference engine (AGENTS.md)
**/*.mdx: Pages should be written as MDX files with YAML frontmatter
Use active voice and second person ("you") in documentation
Keep sentences concise with one idea per sentence in documentation
Use sentence case for headings in documentation
Bold UI elements in documentation (e.g., Click Settings)
Use code formatting for file names, commands, paths, and code references in documentation
Files:
webhooks/overview.mdxwebhooks/managing-webhooks.mdxwebhooks/troubleshooting.mdx
🪛 LanguageTool
webhooks/troubleshooting.mdx
[style] ~19-~19: To form a complete sentence, be sure to include a subject.
Context: ...e message.received. - schemaVersion should be raw-inbound.v1 for Standard Webhoo...
(MISSING_IT_THERE)
🔇 Additional comments (2)
webhooks/overview.mdx (1)
28-28: LGTM!webhooks/managing-webhooks.mdx (1)
48-56: LGTM!
| Walk through this checklist in order: | ||
| - `enabled` must be `true` and `status` must be `active`. | ||
| - `eventTypes` must include `message.received`. | ||
| - `schemaVersion` should be `raw-inbound.v1` for Standard Webhooks delivery. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Use the public endpoint schema ID here.
raw-inbound.v1 is the raw envelope's internal schemaVersion, not the public schema ID used by the endpoint record. This checklist can mark valid endpoints as misconfigured. Check the endpoint's public schema ID here, and document raw-inbound.v1 only for the delivered envelope.
As per PR objectives, keep the raw envelope's internal schemaVersion separate from public endpoint schema IDs.
🧰 Tools
🪛 LanguageTool
[style] ~19-~19: To form a complete sentence, be sure to include a subject.
Context: ...e message.received. - schemaVersion should be raw-inbound.v1 for Standard Webhoo...
(MISSING_IT_THERE)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@webhooks/troubleshooting.mdx` at line 19, Update the Standard Webhooks
troubleshooting checklist to reference the endpoint’s public schema ID instead
of using raw-inbound.v1. Document raw-inbound.v1 only when describing the
delivered envelope’s internal schemaVersion, keeping these identifiers clearly
separate.
|
CodeRabbit (@coderabbitai) review |
✅ Action performedReview finished.
|
There was a problem hiding this comment.
🧹 Nitpick comments (1)
webhooks/managing-webhooks.mdx (1)
36-38: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueSplit the two actions into separate sentences.
Line 36 combines current delivery handling with future upgrade preparation. Use one sentence for each action.
Proposed revision
-For a `normalized-events.v1` endpoint, use `signingSecret` for current -deliveries and retain the complete `whsec_` `standardSigningSecret` for a future -upgrade to `raw-inbound.v1`. +For a `normalized-events.v1` endpoint, use `signingSecret` for current +deliveries. Retain the complete `whsec_` `standardSigningSecret` for a future +upgrade to `raw-inbound.v1`.As per coding guidelines, “Keep sentences concise with one idea per sentence in documentation.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@webhooks/managing-webhooks.mdx` around lines 36 - 38, In the documentation sentence describing normalized-events.v1 endpoints, separate the current-delivery use of signingSecret from retaining the complete whsec_ standardSigningSecret for a future raw-inbound.v1 upgrade into two concise sentences.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@webhooks/managing-webhooks.mdx`:
- Around line 36-38: In the documentation sentence describing
normalized-events.v1 endpoints, separate the current-delivery use of
signingSecret from retaining the complete whsec_ standardSigningSecret for a
future raw-inbound.v1 upgrade into two concise sentences.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 5deb5ed4-1b38-4626-9642-1d2f6ac09eb2
📒 Files selected for processing (1)
webhooks/managing-webhooks.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (1)
**/*.mdx
📄 CodeRabbit inference engine (AGENTS.md)
**/*.mdx: Pages should be written as MDX files with YAML frontmatter
Use active voice and second person ("you") in documentation
Keep sentences concise with one idea per sentence in documentation
Use sentence case for headings in documentation
Bold UI elements in documentation (e.g., Click Settings)
Use code formatting for file names, commands, paths, and code references in documentation
Files:
webhooks/managing-webhooks.mdx
🔇 Additional comments (1)
webhooks/managing-webhooks.mdx (1)
66-68: LGTM!
|
CodeRabbit (@coderabbitai) review |
✅ Action performedReview finished.
|
|
CodeRabbit (@coderabbitai) review |
✅ Action performedReview finished.
|
|
CodeRabbit (@coderabbitai) review |
|
1 participant
Summary
normalized-events.v1andraw-inbound.v1schema IDs, raw-by-default creation, one-way upgrades, and one-time secret retentionschemaVersion: 1is an internal envelope revision, distinct from the endpoint's public schema IDWhy
Customers need one coherent contract for delivery behavior across Fusor and Spectrum Cloud, including explicit payload-schema pinning and the current recovery boundary.
Related changes
The Standard Webhooks payload-size recommendation is intentionally out of scope; these docs do not introduce or change a payload-size limit.
Validation
pnpm exec vellum buildDOCS_GH_TOKEN=$(gh auth token) pnpm docs:generatepnpm lintpnpm typecheck:docsSummary by CodeRabbit
message.receivedevents, required headers, raw-body verification, replay protection, secret rotation, and legacy compatibility.