devrev-Python-SDK 3.0.3__tar.gz → 3.1.0__tar.gz

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/.augment/agents/foreman.md

@@ -1,30 +1,43 @@
 ---
 name: foreman
-description: Orchestrates feature development from GitHub issue to PR creation
+description: Orchestrates feature development from GitHub or Linear issue to PR creation
 model: prism-b
 color: indigo
 ---
 
-You are a Foreman agent that orchestrates complete feature development from GitHub issue analysis to PR creation.
+You are a Foreman agent that orchestrates complete feature development from GitHub or Linear issue analysis to PR creation.
 
 ## Your Role
 
-Accept a GitHub issue (often an Epic with linked sub-issues) and coordinate parallel Builder agents to implement the feature end-to-end.
+Accept a GitHub or Linear issue (often an Epic with linked sub-issues) and coordinate parallel Builder agents to implement the feature end-to-end while preserving the privacy boundary between public and private trackers.
+
+## Issue Sources and Privacy Model
+
+- GitHub issues are public or externally visible. They may be created by external users and should be copied into Linear before implementation.
+- Linear issues are private/internal. They must stay private and must never be copied into GitHub.
+- Linear is the primary internal tracking system for active implementation work.
+- For GitHub-origin work, find or create a Linear issue that copies only public GitHub content and includes the GitHub URL/source number. Use the Linear issue as the primary tracking issue.
+- Do not post Linear-only details, internal analysis, private acceptance criteria, or Linear URLs back to GitHub.
 
 ## Trigger
 
-Activated when a human requests implementation of an issue or a feature issue (e.g., "Implement issue #15"). When
-the human mentions a feature without an issue you will try to find the issue in github, and if not you will work with 
-the human to create an issue. You can not work on a feature without a github issue.
+Activated when a human requests implementation of an issue or a feature issue (e.g., "Implement issue #15" or
+"Implement CUSS-220"). When the human mentions a feature without an issue, try to find a matching issue in Linear and
+GitHub. If no issue exists, work with the human to create a Linear issue. You cannot work on a feature without a GitHub
+or Linear issue, and private/internal requests should be tracked in Linear rather than GitHub.
 
 ## Workflow
 
 ### Phase 1: Analysis & Planning
 
 1. **Fetch Issue Context**:
-   - Get the GitHub issue details via MCP, `gh` tool or API
-   - Parse issue body for referenced issues (`#123`, `Closes #456`)
-   - Fetch GitHub's linked issues/PRs
+   - Resolve the provided identifier as either GitHub or Linear.
+   - For GitHub issue numbers, `#123`, or GitHub issue URLs, fetch GitHub issue details via MCP, `gh` tool, or API.
+   - For Linear identifiers such as `CUSS-220`, fetch Linear issue details via Linear tools.
+   - If a GitHub issue is found, find or create a Linear issue before implementation. Search Linear for the GitHub URL or `Source: GitHub #{number}` first to avoid duplicate imports. Copy the public GitHub title/body/URL and source metadata only when a new Linear issue is needed, then treat the Linear issue as the primary tracking issue.
+   - If a Linear issue is found, use it directly and do not copy it to GitHub.
+   - If both sources match or neither source matches, ask the human for clarification before proceeding.
+   - Parse issue body for referenced issues (`#123`, `Closes #456`, `TEAM-123`) and fetch linked issues/PRs from the relevant source.
    - Build a complete picture of requirements
 
 2. **Understand the Codebase**:
@@ -39,8 +52,9 @@ the human to create an issue. You can not work on a feature without a github iss
 3. **Create Implementation Plan**:
    ```json
    {
-     "issue": "#15",
-     "feature_branch": "feature/issue-15-job-management",
+     "source_issue": "GitHub #15",
+     "tracking_issue": "ENG-123",
+     "feature_branch": "feature/issue-eng-123-job-management",
      "components": [
        {"name": "JobModel", "type": "model", "dependencies": [], "parallel_group": 1},
        {"name": "JobService", "type": "service", "dependencies": ["JobModel"], "parallel_group": 2},
@@ -55,10 +69,10 @@ the human to create an issue. You can not work on a feature without a github iss
 
 1. **Create Feature Branch**:
 
-ALways work in a branch per feature. Name the branch after the issue number and a slugified version of the issue title.
+Always work in a branch per feature. Name the branch after the active tracking issue identifier and a slugified version of the issue title.
    ```bash
    git checkout main && git pull origin main
-   git checkout -b feature/issue-{number}-{slug}
+   git checkout -b feature/issue-{tracking-id}-{slug}
    ```
 
 2. **Dispatch Builder agents**:
@@ -80,17 +94,22 @@ meticulous in updating the task list as you go. If there are remaining tasks in
 
 1. **Commit Strategy**:
    - One logical commit per component or related group
-   - Format: `feat: add {component} for {feature} (#{issue})`
+   - Format for Linear-origin work: `feat: add {component} for {feature} ({linear-issue})`
+   - Format for GitHub-origin work copied to Linear: `feat: add {component} for {feature} ({linear-issue}, #{github-issue})`
    - Include co-authored-by for Builder agents if applicable
 
-2. **Update GitHub Issues**:
-   - Add progress comments to the issue or issues related as progress is made using the github mcp the `gh` cli tool or the github api.
-   - Link related issues as "Referenced by"
+2. **Update Tracking Issues**:
+   - Add detailed progress comments to the active Linear issue as progress is made.
+   - For GitHub-origin work, optionally add public-safe progress comments to the GitHub issue using the GitHub MCP tools, `gh` CLI, or GitHub API.
+   - Do not expose Linear-only details, private acceptance criteria, internal links, or Linear URLs in public GitHub comments.
+   - Link related issues as "Referenced by" in the appropriate tracker when supported.
 
 3. **Create PR**:
    - Push feature branch
    - Create PR with comprehensive description
    - Include: Summary, Components Added, Testing, Related Issues
+   - For Linear-origin work, keep private issue details out of public PR text; use a concise internal reference only when appropriate.
+   - For GitHub-origin work, link the public GitHub issue and reference the Linear tracking issue only if doing so does not expose private context.
    - Include the number of subagents used to implement the feature.
    - Note any issues or problems you had along the way.
    - Hand off to `pr-review-boss` for the review and merge lifecycle
@@ -101,7 +120,8 @@ you are not sure what to do next. You are highly motivated to work autonomously
 guidance from the issues, the codebase and the documentation (md files) in the repository.
 
 After PR creation:
-1. Check for next prioritized GitHub issue (by milestone, label priority)
+1. Check for next prioritized Linear issue first, then public GitHub issues if no Linear issue is ready.
+   Find or create the Linear copy for any selected GitHub issue before starting implementation.
 2. Begin new feature branch and repeat workflow
 3. If you are not sure what to do next, ask the human for guidance.
 4. Continue until no actionable issues remain
@@ -157,7 +177,9 @@ After PR creation:
 
 ## Constraints
 
-- **ALL** commits must reference the GitHub issue
+- **ALL** commits must reference the active tracking issue. For GitHub-origin work, include both the Linear tracking issue and public GitHub issue when practical.
+- **NEVER** copy Linear issue content to GitHub or otherwise expose private Linear context in public GitHub comments, PR descriptions, branches, or commit messages.
+- **ALWAYS** copy public GitHub issues to Linear before implementation so internal work is tracked privately.
 - **NEVER** introduce deprecated library versions
 - **ALWAYS** verify library docs are current before using
 - **HANDLE** errors explicitly - no silent failures
@@ -172,16 +194,16 @@ After PR creation:
 
 ## Output Format
 
-Post status updates to the GitHub issue:
+Post detailed status updates to the active Linear issue. For GitHub-origin work, GitHub status updates must be public-safe summaries only:
 This is an illustrative example. 
-Use the github mcp, the `gh` cli tool or the github api to post updates.`
+Use the Linear tools for private/internal updates. Use the GitHub MCP, the `gh` CLI tool, or the GitHub API only for public-safe GitHub updates.`
 ```markdown
 ## 🏗️ Builder Coordinator Progress
 
 🛠️ 3 subagent groups used, with 2 builders in each group.
 
 ### Phase 1: Planning ✅
-- Analyzed issue #15 and 3 linked issues
+- Analyzed tracking issue ENG-123 and source issue #15
 - Identified 5 components to build
 
 ### Phase 2: Development 🔄
@@ -191,7 +213,7 @@ Use the github mcp, the `gh` cli tool or the github api to post updates.`
 - ⏳ JobTemplates (templates/jobs/*.html)
 
 ### Phase 3: PR Creation ⏳
-- Branch: `feature/issue-15-job-management`
+- Branch: `feature/issue-eng-123-job-management`
 - Estimated completion: 15 minutes
 ```
 

devrev_python_sdk-3.1.0/.augment/commands/foreman-work.md

@@ -0,0 +1,96 @@
+---
+description: Start working on a GitHub or Linear issue using the Foreman agent
+argument-hint: [issue-id-or-number]
+model: prism-b
+---
+
+# Foreman Work Command
+
+You are invoking the **Foreman** agent to work on a GitHub or Linear issue. The Foreman orchestrates complete feature development from issue analysis to PR creation while preserving the privacy boundary between public GitHub issues and private Linear issues.
+
+## Arguments
+
+- `$ARGUMENTS` - Optional GitHub issue number/URL or Linear issue identifier (e.g., `123`, `#123`, `https://github.com/.../issues/123`, or `CUSS-220`)
+
+## Workflow
+
+### If an issue identifier is provided:
+
+Resolve and work on issue `$ARGUMENTS`:
+
+1. Determine the issue source:
+   - If `$ARGUMENTS` is a GitHub issue number (`123`, `#123`) or GitHub issue URL, fetch it using `gh issue view`, the GitHub API, or the GitHub MCP tools.
+   - If `$ARGUMENTS` is a Linear identifier (`TEAM-123`, e.g. `CUSS-220`), fetch it from Linear.
+   - If the identifier is ambiguous, try the most likely source first and ask the user only if both sources match or neither source matches.
+2. If a GitHub issue is found, copy it to Linear before implementation:
+   - Search Linear first for an existing issue that references the GitHub URL or `Source: GitHub #{number}` to avoid duplicate imports.
+   - Create a Linear issue with the GitHub issue title, public issue body, GitHub URL, labels/milestone when useful, and a clear `Source: GitHub #{number}` note.
+   - If an imported Linear issue already exists, reuse it as the primary tracking issue instead of creating a duplicate.
+   - Treat the new Linear issue as the primary tracking issue for planning and progress updates.
+   - Do **not** post private Linear details back to GitHub. Public GitHub comments must remain public-safe.
+3. If a Linear issue is found, use it directly:
+   - Do **not** copy Linear issue content to GitHub.
+   - Keep private/internal context in Linear only.
+4. Analyze the issue requirements and linked issues in the appropriate source system.
+5. Create an implementation plan.
+6. Create a feature branch following the naming convention: `feature/issue-{tracking-id}-{slug}` where `tracking-id` is the Linear identifier for Linear-origin or GitHub-imported work.
+7. Coordinate builder agents to implement components in parallel where possible.
+8. Run tests and ensure quality checks pass.
+9. Create a PR when implementation is complete.
+10. Hand off to `pr-review-boss` for the review lifecycle.
+
+### If NO issue identifier is provided:
+
+Help the user select an issue to work on:
+
+1. Fetch open GitHub issues that are NOT in progress using:
+   ```bash
+   gh issue list --state open --json number,title,labels,milestone --limit 20
+   ```
+
+2. Fetch actionable Linear issues that are NOT completed, canceled, in progress, or WIP using the Linear tools.
+
+3. Filter out issues in either source that have "in progress" or "wip" labels/states.
+
+4. Present the user with a numbered list of available issues, clearly marking the source:
+   ```
+   Available Issues:
+   
+   1. GitHub #42 - Implement user authentication
+   2. Linear CUSS-220 - Support API key authentication for MCP endpoints
+   3. GitHub #35 - Fix pagination on dashboard
+   4. Linear ENG-29 - Update API rate limiting
+   
+   Enter the number of the issue you want to work on (1-4), or type 'q' to quit:
+   ```
+
+5. Wait for user input to select an issue.
+
+6. Once selected, proceed with the full foreman workflow for that issue. If the selected issue is from GitHub, find or create the Linear copy first and then work from the Linear issue.
+
+## Technical Standards
+
+Follow all standards defined in the foreman agent:
+- Python 3.11+ with strict typing
+- Pydantic v2 for data models
+- Google-style docstrings
+- Latest stable library versions
+- SOC-2 security mindset (no PII in logs, secure defaults)
+
+## Constraints
+
+- **ALL** commits must reference the active tracking issue. For GitHub-origin work, reference both the Linear tracking issue and the public GitHub issue when practical.
+- **NEVER** copy Linear issue content to GitHub or otherwise expose private Linear context in public GitHub comments, PRs, branches, or commit messages.
+- **ALWAYS** copy public GitHub issues to Linear before implementation so internal work is tracked privately.
+- **NEVER** introduce deprecated library versions
+- **ALWAYS** verify library docs are current before using
+- **HANDLE** errors explicitly - no silent failures
+- **UPDATE** the task list as you work to track progress
+
+## Related Agents
+
+You may dispatch these sub-agents as needed:
+- `sub-agent-builder` - For implementing specific components
+- `sub-agent-tester` - For comprehensive test coverage
+- `sub-agent-documentation` - For README/CHANGELOG updates
+

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devrev-Python-SDK
-Version: 3.0.3
+Version: 3.1.0
 Summary: A modern, type-safe Python SDK for the DevRev API
 Project-URL: Homepage, https://github.com/mgmonteleone/py-dev-rev
 Project-URL: Documentation, https://github.com/mgmonteleone/py-dev-rev
@@ -75,7 +75,7 @@ Description-Content-Type: text/markdown
 
 # py-devrev
 
-A modern, type-safe Python SDK for the DevRev API.
+A modern, type-safe Python SDK and MCP for the DevRev API.
 
 [![Built with Augment](https://img.shields.io/badge/Built%20with-Auggie-6366f1?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDIgMTloMjBMMTIgMnptMCAzLjc1TDE4LjI1IDE3SDUuNzVMMTIgNS43NXoiLz48L3N2Zz4=)](https://www.augmentcode.com/)
 [![PyPI Version](https://img.shields.io/pypi/v/devrev-python-sdk.svg)](https://pypi.org/project/devrev-Python-SDK/)
@@ -159,7 +159,7 @@ This SDK is generated and maintained from the official DevRev OpenAPI specificat
 
 ### MCP Server (AI Integration)
 
-- ✅ **78+ MCP Tools** — Full CRUD for tickets, accounts, users, articles, and all DevRev resources
+- ✅ **83+ MCP Tools** — Full CRUD for tickets, accounts, users, articles, webhooks, and all DevRev resources
 - ✅ **7 Resource Templates** — `devrev://` URI scheme for AI-accessible data browsing
 - ✅ **8 Workflow Prompts** — Pre-built triage, escalation, investigation, and reporting workflows
 - ✅ **3 Transport Modes** — stdio (local), Streamable HTTP (production), SSE (legacy)
@@ -725,7 +725,7 @@ The DevRev MCP Server exposes the full DevRev platform as [Model Context Protoco
 
 ### MCP Server Features
 
-- **78+ MCP Tools** — Full CRUD for tickets, accounts, users, conversations, articles, parts, tags, groups, timeline, links, SLAs, plus beta tools (search, recommendations, incidents, engagements)
+- **83+ MCP Tools** — Full CRUD for tickets, accounts, users, conversations, articles, parts, tags, groups, timeline, links, SLAs, webhooks, plus beta tools (search, recommendations, incidents, engagements)
 - **7 Resource Templates** — `devrev://` URI scheme for browsing tickets, accounts, articles, users, parts, conversations
 - **8 Workflow Prompts** — Triage, draft response, escalate, summarize account, investigate, weekly report, find similar, onboard customer
 - **3 Transports** — stdio (local dev), Streamable HTTP (production), SSE (legacy)

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/README.md

@@ -1,6 +1,6 @@
 # py-devrev
 
-A modern, type-safe Python SDK for the DevRev API.
+A modern, type-safe Python SDK and MCP for the DevRev API.
 
 [![Built with Augment](https://img.shields.io/badge/Built%20with-Auggie-6366f1?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDIgMTloMjBMMTIgMnptMCAzLjc1TDE4LjI1IDE3SDUuNzVMMTIgNS43NXoiLz48L3N2Zz4=)](https://www.augmentcode.com/)
 [![PyPI Version](https://img.shields.io/pypi/v/devrev-python-sdk.svg)](https://pypi.org/project/devrev-Python-SDK/)
@@ -84,7 +84,7 @@ This SDK is generated and maintained from the official DevRev OpenAPI specificat
 
 ### MCP Server (AI Integration)
 
-- ✅ **78+ MCP Tools** — Full CRUD for tickets, accounts, users, articles, and all DevRev resources
+- ✅ **83+ MCP Tools** — Full CRUD for tickets, accounts, users, articles, webhooks, and all DevRev resources
 - ✅ **7 Resource Templates** — `devrev://` URI scheme for AI-accessible data browsing
 - ✅ **8 Workflow Prompts** — Pre-built triage, escalation, investigation, and reporting workflows
 - ✅ **3 Transport Modes** — stdio (local), Streamable HTTP (production), SSE (legacy)
@@ -650,7 +650,7 @@ The DevRev MCP Server exposes the full DevRev platform as [Model Context Protoco
 
 ### MCP Server Features
 
-- **78+ MCP Tools** — Full CRUD for tickets, accounts, users, conversations, articles, parts, tags, groups, timeline, links, SLAs, plus beta tools (search, recommendations, incidents, engagements)
+- **83+ MCP Tools** — Full CRUD for tickets, accounts, users, conversations, articles, parts, tags, groups, timeline, links, SLAs, webhooks, plus beta tools (search, recommendations, incidents, engagements)
 - **7 Resource Templates** — `devrev://` URI scheme for browsing tickets, accounts, articles, users, parts, conversations
 - **8 Workflow Prompts** — Triage, draft response, escalate, summarize account, investigate, weekly report, find similar, onboard customer
 - **3 Transports** — stdio (local dev), Streamable HTTP (production), SSE (legacy)

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/docs/changelog.md

@@ -13,6 +13,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+## [3.1.0] - 2026-06-16
+
+### Added
+
+- **Webhook management MCP tools** (CSS-1041) — New `devrev_webhooks_*` MCP
+  tools exposing the existing `WebhooksService` through the MCP server:
+  `devrev_webhooks_list` and `devrev_webhooks_get` (read-only), plus
+  `devrev_webhooks_create`, `devrev_webhooks_update`, and
+  `devrev_webhooks_delete` (registered only when destructive tools are
+  enabled). The module follows the established tool conventions (DON ID
+  validation, paginated list responses, `WebhookStatus` resolution on update)
+  and is registered in the core (non-beta) tool block. Documentation in
+  `docs/mcp/tools-reference.md` now covers all five tools plus an advisory
+  section on event types, target URL requirements, the signing `secret`, and
+  the webhook status lifecycle.
+
 ## [3.0.1] - 2026-04-22
 
 ### Changed

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/docs/mcp/tools-reference.md

@@ -6,7 +6,7 @@ icon: material/tools
 
 Complete reference of all MCP capabilities provided by the DevRev MCP Server.
 
-## Tools (83+)
+## Tools (88+)
 
 Tools are the primary way AI assistants interact with DevRev. Each tool maps to one or more DevRev API endpoints.
 
@@ -148,12 +148,37 @@ issues (engineering), and tasks.
 
 ### Webhooks
 
+Webhooks deliver DevRev events to an external HTTPS endpoint. Each webhook has a
+target `url`, an optional list of `event_types` to subscribe to (defaults to all
+events), and an optional `secret` used to sign payloads so the receiver can
+verify authenticity. A webhook's `status` moves through `unverified` → `active`
+once DevRev confirms the endpoint, and can be set to `inactive` to pause
+delivery.
+
 | Tool | Description |
 |------|-------------|
 | `devrev_webhooks_list` | List webhooks |
 | `devrev_webhooks_get` | Get webhook details |
 | `devrev_webhooks_create` | Create a webhook |
-| `devrev_webhooks_update` | Update a webhook |
+| `devrev_webhooks_update` | Update a webhook (url, event types, status) |
+| `devrev_webhooks_delete` | Delete a webhook |
+
+**Managing webhooks**
+
+- **Target URL** must be a publicly reachable HTTPS endpoint that responds to
+  DevRev's verification handshake; until it does, the webhook stays
+  `unverified` and no events are delivered.
+- **Event types** scope which events are sent. Omit `event_types` on create to
+  receive all event types, or pass a specific list (e.g. `work_created`,
+  `work_updated`) to narrow delivery.
+- **Secret** is a shared signing key — store it as a secret on the receiving
+  service and use it to verify each payload's signature. Never log or commit it.
+- **Status lifecycle**: `unverified` (awaiting handshake) → `active` (delivering)
+  ↔ `inactive` (paused). Use `devrev_webhooks_update` with `status` to pause or
+  resume a webhook.
+- **Typical workflow**: `devrev_webhooks_create` (register the endpoint) → verify
+  the endpoint so it becomes `active` → `devrev_webhooks_list` / `devrev_webhooks_get`
+  to confirm configuration → `devrev_webhooks_delete` when it is no longer needed.
 
 ### Beta Tools
 

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devrev-Python-SDK"
-version = "3.0.3"
+version = "3.1.0"
 description = "A modern, type-safe Python SDK for the DevRev API"
 readme = "README.md"
 requires-python = ">=3.11"

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/src/devrev_mcp/server.py

@@ -249,6 +249,7 @@ from devrev_mcp.tools import slas as _slas_tools  # noqa: E402, F401
 from devrev_mcp.tools import tags as _tags_tools  # noqa: E402, F401
 from devrev_mcp.tools import timeline as _timeline_tools  # noqa: E402, F401
 from devrev_mcp.tools import users as _users_tools  # noqa: E402, F401
+from devrev_mcp.tools import webhooks as _webhooks_tools  # noqa: E402, F401
 from devrev_mcp.tools import works as _works_tools  # noqa: E402, F401
 
 # Beta tools (only if beta tools are enabled)

devrev_python_sdk-3.1.0/src/devrev_mcp/tools/webhooks.py

@@ -0,0 +1,153 @@
+"""MCP tools for DevRev webhook operations."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from devrev.exceptions import DevRevError
+from devrev.models.webhooks import (
+    WebhooksCreateRequest,
+    WebhooksDeleteRequest,
+    WebhooksGetRequest,
+    WebhooksListRequest,
+    WebhookStatus,
+    WebhooksUpdateRequest,
+)
+from devrev_mcp.server import _config, mcp
+from devrev_mcp.utils.don_id import validate_don_id
+from devrev_mcp.utils.errors import format_devrev_error
+from devrev_mcp.utils.formatting import serialize_model, serialize_models
+from devrev_mcp.utils.pagination import clamp_page_size
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def devrev_webhooks_list(
+    ctx: Context[Any, Any, Any],
+    cursor: str | None = None,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    """List DevRev webhooks.
+
+    Args:
+        cursor: Pagination cursor from a previous response.
+        limit: Maximum number of items to return (default: 25, max: 100).
+    """
+    app = ctx.request_context.lifespan_context
+    try:
+        request = WebhooksListRequest(
+            cursor=cursor,
+            limit=clamp_page_size(
+                limit, default=app.config.default_page_size, maximum=app.config.max_page_size
+            ),
+        )
+        webhooks = await app.get_client().webhooks.list(request)
+        items = serialize_models(list(webhooks))
+        return {"count": len(items), "webhooks": items}
+    except DevRevError as e:
+        raise RuntimeError(format_devrev_error(e)) from e
+
+
+@mcp.tool()
+async def devrev_webhooks_get(
+    ctx: Context[Any, Any, Any],
+    id: str,
+) -> dict[str, Any]:
+    """Get a DevRev webhook by ID.
+
+    Args:
+        id: Webhook ID (e.g., "don:integration:dvrv-us-1:devo/1:webhook/123").
+    """
+    validate_don_id(id, "webhook", "devrev_webhooks_get")
+    app = ctx.request_context.lifespan_context
+    try:
+        request = WebhooksGetRequest(id=id)
+        webhook = await app.get_client().webhooks.get(request)
+        return serialize_model(webhook)
+    except DevRevError as e:
+        raise RuntimeError(format_devrev_error(e)) from e
+
+
+# Destructive tools (only registered when enabled)
+if _config.enable_destructive_tools:
+
+    @mcp.tool()
+    async def devrev_webhooks_create(
+        ctx: Context[Any, Any, Any],
+        url: str,
+        event_types: list[str] | None = None,
+        secret: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new DevRev webhook.
+
+        Args:
+            url: Target URL that will receive webhook event POSTs.
+            event_types: Event types to subscribe to (default: all events).
+            secret: Shared secret used to sign and verify webhook payloads.
+        """
+        app = ctx.request_context.lifespan_context
+        try:
+            request = WebhooksCreateRequest(url=url, event_types=event_types, secret=secret)
+            webhook = await app.get_client().webhooks.create(request)
+            return serialize_model(webhook)
+        except DevRevError as e:
+            raise RuntimeError(format_devrev_error(e)) from e
+
+    @mcp.tool()
+    async def devrev_webhooks_update(
+        ctx: Context[Any, Any, Any],
+        id: str,
+        url: str | None = None,
+        event_types: list[str] | None = None,
+        status: str | None = None,
+    ) -> dict[str, Any]:
+        """Update a DevRev webhook.
+
+        Args:
+            id: Webhook ID to update.
+            url: New target URL.
+            event_types: New list of event types to subscribe to.
+            status: New status (active, inactive, unverified).
+        """
+        validate_don_id(id, "webhook", "devrev_webhooks_update")
+        app = ctx.request_context.lifespan_context
+        try:
+            resolved_status: WebhookStatus | None = None
+            if status is not None:
+                try:
+                    resolved_status = WebhookStatus(status.lower())
+                except ValueError as e:
+                    raise RuntimeError(
+                        f"Invalid webhook status '{status}'. "
+                        "Valid values: active, inactive, unverified."
+                    ) from e
+            request = WebhooksUpdateRequest(
+                id=id, url=url, event_types=event_types, status=resolved_status
+            )
+            webhook = await app.get_client().webhooks.update(request)
+            return serialize_model(webhook)
+        except DevRevError as e:
+            raise RuntimeError(format_devrev_error(e)) from e
+
+    @mcp.tool()
+    async def devrev_webhooks_delete(
+        ctx: Context[Any, Any, Any],
+        id: str,
+    ) -> dict[str, Any]:
+        """Delete a DevRev webhook.
+
+        Args:
+            id: Webhook ID to delete.
+        """
+        validate_don_id(id, "webhook", "devrev_webhooks_delete")
+        app = ctx.request_context.lifespan_context
+        try:
+            request = WebhooksDeleteRequest(id=id)
+            await app.get_client().webhooks.delete(request)
+            return {"deleted": True, "id": id}
+        except DevRevError as e:
+            raise RuntimeError(format_devrev_error(e)) from e

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/src/devrev_mcp/utils/don_id.py

@@ -35,6 +35,7 @@ DON_TYPE_MAP: dict[str, str] = {
     "qa": "question_answer",
     "question_answer": "question_answer",
     "timeline_entry": "timeline_entry",
+    "webhook": "webhook",
 }
 
 TOOL_SUGGESTIONS: dict[str, str] = {
@@ -57,6 +58,7 @@ TOOL_SUGGESTIONS: dict[str, str] = {
     "qa": "devrev_question_answers_get",
     "question_answer": "devrev_question_answers_get",
     "timeline_entry": "devrev_timeline_get",
+    "webhook": "devrev_webhooks_get",
 }
 
 

{devrev_python_sdk-3.0.3 → devrev_python_sdk-3.1.0}/tests/unit/mcp/conftest.py

@@ -176,6 +176,14 @@ def mock_client():
     client.slas.update = AsyncMock()
     client.slas.transition = AsyncMock()
 
+    # Webhooks service
+    client.webhooks = AsyncMock()
+    client.webhooks.list = AsyncMock()
+    client.webhooks.get = AsyncMock()
+    client.webhooks.create = AsyncMock()
+    client.webhooks.update = AsyncMock()
+    client.webhooks.delete = AsyncMock()
+
     # Question Answers service
     client.question_answers = AsyncMock()
     client.question_answers.list = AsyncMock()