Webhooks V2#280
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
Next review available in: 9 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis pull request rewrites Plane webhook documentation for v2 workspace-scoped webhooks. It covers creation, filtering, lifecycle operations, HMAC-SHA256 security, asynchronous delivery and retries, event references, payload schemas, and JSON examples. ChangesWebhooks v2 Complete Documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 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 |
| project_id = "<project-uuid>" Specific project | ||
| ``` | ||
|
|
||
| ## Securing requests |
There was a problem hiding this comment.
we can move this to or nearby delivery and monitoring section
| Whenever an issue is added to the module, the corresponding issue webhook will be triggered. Similarly, any updates made to the cycle issue will also activate the issue webhook. | ||
| ::: | ||
| **workitem.link.created** | ||
|
|
There was a problem hiding this comment.
let's add a workitem.updated event as sample as it has previous_attributes also
{
"version":"v2",
"delivery_id":"2a0d0510-9052-446e-a1c7-a704bbd68cba",
"event_id":"9d508cd9-36c2-44a5-928d-7ee2f2a3b8a8",
"entity_id":"775c5716-5302-4617-bb9f-2cd843911268",
"entity_type":"issue",
"event":"WebhookScope.ScopeChoices.WORK_ITEM_UPDATED",
"webhook_id":"8944ed18-1331-4eae-b9bb-7c40864b8abd",
"workspace_id":"b54ecb0d-e3eb-4986-b238-f83fd8665e65",
"data":{
"id":"775c5716-5302-4617-bb9f-2cd843911268",
"name":"webhook test 3",
"point":"None",
"type_id":"None",
"is_draft":false,
"priority":"none",
"state_id":"067b88e5-304b-4221-ba09-94340dcc36e5",
"label_ids":[],
"parent_id":"None",
"created_at":"2026-03-31T11:44:41.249292+00:00",
"deleted_at":"None",
"project_id":"59e3be42-87ec-4950-99a3-ae639cf2b089",
"sort_order":75535,
"start_date":"None",
"updated_at":"2026-03-31T11:44:41.249304+00:00",
"archived_at":"None",
"external_id":"None",
"sequence_id":3,
"target_date":"None",
"assignee_ids":[ ],
"completed_at":"None",
"workspace_id":"b54ecb0d-e3eb-4986-b238-f83fd8665e65",
"created_by_id":"754009ab-3fb5-424e-909a-b46e9c9d0c4f",
"updated_by_id":"None",
"external_source":"None",
"description_json":{},
"last_activity_at":"2026-03-31T11:44:41.346305+00:00",
"estimate_point_id":"None"
},
"previous_attributes":{
"last_activity_at":"2026-03-31 11:44:41.242868+00"
}
}
|
|
||
| Webhooks in Plane work at the workspace level. A single webhook can subscribe to events from every project in the workspace. There is no per-project webhook configuration. Only Workspace Owners and Admins can create or manage them. | ||
|
|
||
| The current webhook system is v2. V2 payloads use dot-notation event names (e.g., `workitem.created`) and include structured fields for deduplication, diffing, and filtering that were not available in the original version. If you have webhooks created before v2, they appear in the list with a **(deprecated)** tag. They still deliver but do not receive any v2 fields. Recreate them as new webhooks to get the full v2 feature set. |
There was a problem hiding this comment.
we can highlight about v1 deprecation and how to switch to v2 as it needs some attention
There was a problem hiding this comment.
you mean as callout @Saurabhkmr98 or you want to add more information to this? i have updated that area. check again
Saurabhkmr98
left a comment
Saurabhkmr98
left a comment
There was a problem hiding this comment.
somethings that we can improve
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/dev-tools/intro-webhooks.md (1)
1-426:⚠️ Potential issue | 🟠 Major | ⚡ Quick winPrettier CI is currently failing for this file and must be fixed before merge.
CI / Prettierreports--checkfailure ondocs/dev-tools/intro-webhooks.md. Please run Prettier and commit the formatted output so the pipeline is green.As per coding guidelines, "
**/*.{ts,tsx,js,jsx,vue,json,md,mts}: Prettier formatting checks must pass in CI, with 120 character line width, 2-space indent, semicolons, double quotes, and ES5 trailing commas".🤖 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 `@docs/dev-tools/intro-webhooks.md` around lines 1 - 426, Prettier check is failing for docs/dev-tools/intro-webhooks.md; run Prettier with the repo's formatting rules (120 char printWidth, 2-space indent, semicolons, double quotes, trailingComma: "es5") on that markdown file (or run the project's preconfigured formatter script), stage the updated docs/dev-tools/intro-webhooks.md and commit the formatted output so CI Prettier --check passes.
🤖 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 `@docs/dev-tools/intro-webhooks.md`:
- Around line 380-390: The example payload labeled workitem.link.updated is
inconsistent with the v2 contract: replace the current event value
WebhookScope.ScopeChoices.WORK_ITEM_UPDATED and the entity_type "issue" with the
v2 event key and matching entity semantics (set "event" to
"workitem.link.updated" and use the v2 entity name for links, e.g.,
"entity_type": "workitem_link"), ensure the entity_id refers to the link
resource id (not an issue id), keep "version":"v2" and valid UUIDs for
delivery_id/event_id/webhook_id, and remove the non-dot-notation enum reference
so the JSON matches the documented v2 schema.
- Around line 103-109: The fenced code block under "Expression syntax"
containing lines like priority = "urgent", priority in ["urgent", "high"],
state_group = "started", assignee_id = "<user-uuid>", and project_id =
"<project-uuid>" lacks a language identifier; add a language tag (e.g., ```text)
to the opening fence so the block becomes ```text to satisfy markdown linting.
---
Outside diff comments:
In `@docs/dev-tools/intro-webhooks.md`:
- Around line 1-426: Prettier check is failing for
docs/dev-tools/intro-webhooks.md; run Prettier with the repo's formatting rules
(120 char printWidth, 2-space indent, semicolons, double quotes, trailingComma:
"es5") on that markdown file (or run the project's preconfigured formatter
script), stage the updated docs/dev-tools/intro-webhooks.md and commit the
formatted output so CI Prettier --check passes.
🪄 Autofix (Beta)
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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8a39cbcd-254a-4601-80ba-bd6a70e8a49d
📒 Files selected for processing (2)
docs/dev-tools/intro-webhooks.mddocs/public/images/webhooks/create-webhook.webp
| ``` | ||
| priority = "urgent" Single value | ||
| priority in ["urgent", "high"] Multiple values | ||
| state_group = "started" State group match | ||
| assignee_id = "<user-uuid>" Specific assignee | ||
| project_id = "<project-uuid>" Specific project | ||
| ``` |
There was a problem hiding this comment.
Add a language identifier to the fenced code block.
The block under Expression syntax should specify a language (e.g., text) to satisfy markdown linting.
Suggested patch
-```
+```text
priority = "urgent" Single value
priority in ["urgent", "high"] Multiple values
state_group = "started" State group match
assignee_id = "<user-uuid>" Specific assignee
project_id = "<project-uuid>" Specific project</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 103-103: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 `@docs/dev-tools/intro-webhooks.md` around lines 103 - 109, The fenced code
block under "Expression syntax" containing lines like priority = "urgent",
priority in ["urgent", "high"], state_group = "started", assignee_id =
"<user-uuid>", and project_id = "<project-uuid>" lacks a language identifier;
add a language tag (e.g., ```text) to the opening fence so the block becomes
```text to satisfy markdown linting.
| **workitem.link.updated** | ||
|
|
||
| ```json | ||
| { | ||
| "version":"v2", | ||
| "delivery_id":"2a0d0510-9052-446e-a1c7-a704bbd68cba", | ||
| "event_id":"9d508cd9-36c2-44a5-928d-7ee2f2a3b8a8", | ||
| "entity_id":"775c5716-5302-4617-bb9f-2cd843911268", | ||
| "entity_type":"issue", | ||
| "event":"WebhookScope.ScopeChoices.WORK_ITEM_UPDATED", | ||
| "webhook_id":"8944ed18-1331-4eae-b9bb-7c40864b8abd", |
There was a problem hiding this comment.
workitem.link.updated example is internally inconsistent with the documented v2 contract.
This sample mixes incompatible values: heading says workitem.link.updated, but event is WebhookScope.ScopeChoices.WORK_ITEM_UPDATED (non-dot notation and different event), and entity_type is issue. Please replace this with a payload that matches the stated v2 event key and entity semantics.
🤖 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 `@docs/dev-tools/intro-webhooks.md` around lines 380 - 390, The example payload
labeled workitem.link.updated is inconsistent with the v2 contract: replace the
current event value WebhookScope.ScopeChoices.WORK_ITEM_UPDATED and the
entity_type "issue" with the v2 event key and matching entity semantics (set
"event" to "workitem.link.updated" and use the v2 entity name for links, e.g.,
"entity_type": "workitem_link"), ensure the entity_id refers to the link
resource id (not an issue id), keep "version":"v2" and valid UUIDs for
delivery_id/event_id/webhook_id, and remove the non-dot-notation enum reference
so the JSON matches the documented v2 schema.
2 participants
Description
Type of Change
Screenshots and Media (if applicable)
Test Scenarios
References
Summary by CodeRabbit