docs: add webhook payload and testing documentation#29759
Conversation
Document webhook payload shapes by trigger, clarify meeting start/end timing, and add local testing guidance with ngrok. Fixes calcom#15033
|
Welcome to Cal.diy, @akshitj11! Thanks for opening this pull request. A few things to keep in mind:
A maintainer will review your PR soon. Thanks for contributing! |
github-actions
Bot
added
community
📝 WalkthroughWalkthroughAdded a Webhooks section to the documentation navigation and created a page describing Cal.diy webhook payload versioning, trigger-specific structures, example payloads, local testing through a tunnel, subscriber setup, event triggering, and source locations for versioned payload builders. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
apps/docs/content/webhooks.mdx (3)
58-64: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd payload details for
FORM_SUBMITTEDandOOO_CREATED.These events get only a single sentence each with no payload structure or example. The PR objective asks to document payload structures for all webhook events. Even a brief example payload would improve completeness and consistency with the recording events section.
🤖 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 `@apps/docs/content/webhooks.mdx` around lines 58 - 64, Add payload documentation for the FORM_SUBMITTED and OOO_CREATED sections, including each event’s payload structure and a brief representative example consistent with the existing recording-events documentation style.
15-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDocument the payment event payload structure.
The description "payment-specific payloads with booking and payment metadata" is too vague to be actionable. Integrators need to know the actual fields. Consider adding an example JSON payload similar to the recording events section.
🤖 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 `@apps/docs/content/webhooks.mdx` around lines 15 - 17, Expand the Payment events section near BOOKING_PAYMENT_INITIATED and BOOKING_PAID with an example JSON payload, following the format used by the recording events section and showing the concrete booking and payment metadata fields integrators receive.
9-13: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd an example JSON payload for booking events.
The recording events section includes full JSON examples, but the booking events section only lists field names. Since booking events are the most commonly used triggers, an example payload would help integrators validate their handlers against the actual shape. The PR objective asks to document payload structures for all webhook events.
🤖 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 `@apps/docs/content/webhooks.mdx` around lines 9 - 13, Add a representative JSON payload example to the booking events section in webhooks.mdx, covering the documented payload fields and realistic values so integrators can validate handlers against the actual booking event shape. Keep the existing list of shared booking fields and match the formatting used by the recording event examples.
🤖 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 `@apps/docs/content/webhooks.mdx`:
- Around line 58-64: Add payload documentation for the FORM_SUBMITTED and
OOO_CREATED sections, including each event’s payload structure and a brief
representative example consistent with the existing recording-events
documentation style.
- Around line 15-17: Expand the Payment events section near
BOOKING_PAYMENT_INITIATED and BOOKING_PAID with an example JSON payload,
following the format used by the recording events section and showing the
concrete booking and payment metadata fields integrators receive.
- Around line 9-13: Add a representative JSON payload example to the booking
events section in webhooks.mdx, covering the documented payload fields and
realistic values so integrators can validate handlers against the actual booking
event shape. Keep the existing list of shared booking fields and match the
formatting used by the recording event examples.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 13d23bbe-a7f8-44b2-8fcd-6e1c383741b1
📒 Files selected for processing (2)
apps/docs/content/_meta.tsapps/docs/content/webhooks.mdx
Address CodeRabbit review feedback by documenting representative booking, payment, form, and OOO webhook payload shapes.
|
Addressed CodeRabbit feedback , added JSON payload examples for booking, payment, FORM_SUBMITTED, and OOO_CREATED events. |
|
CodeRabbit fixes pushed. Please add the |
1 participant
What does this PR do?
Integrators had no published reference for Cal.diy webhook payload shapes or how to test webhooks locally — they had to read
packages/features/webhooks/lib/factory/source code.This PR adds a Webhooks documentation page covering payload structures by trigger, clarifies that
MEETING_STARTED/MEETING_ENDEDfire at scheduled booking times (not in-call events), documents local testing with ngrok, and includes JSON examples for all major event types.apps/docs/content/webhooks.mdxand sidebar nav entryVisual Demo (For contributors especially)
A visual demonstration is strongly recommended, for both the original and new change (video / image - any one).
Video Demo (if applicable):
Image Demo (if applicable):
Mandatory Tasks (DO NOT REMOVE)
How should this be tested?
yarn devoryarn dx) to render the docs site.packages/features/webhooks/lib/factory/versioned/v2021-10-20/.packages/features/webhooks/lib/factory/.