Webhooks V2#280
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
More reviews will be available in 56 minutes and 3 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis pull request rewrites the Plane webhooks documentation to focus on v2 specifications and workspace-scoped webhooks. It covers creation workflow, work-item filtering modes (Basic and PQL), webhook lifecycle management, HMAC-SHA256 request security, asynchronous delivery with retry semantics, and comprehensive event/payload reference with JSON examples. ChangesWebhooks v2 Complete Documentation
🎯 3 (Moderate) | ⏱️ ~18 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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