feat: add webhook receiver helpers

Author: zelentsov-dev

ASC-COVERAGE-MATRIX-2026-05-05.md

@@ -9,6 +9,7 @@ Source baseline:
 
 Update 2026-05-07: automated OpenAPI coverage tooling is now available. See `ASC-OPENAPI-COVERAGE-GENERATED.md` for the generated Apple 4.3 path/operation matrix.
 Update 2026-05-08: accessibility declaration management is covered by `accessibility_*` tools.
+Update 2026-05-08: local webhook receiver helpers are available for signature verification, payload parsing, and event/delivery triage.
 
 This matrix tracks current `asc-mcp` coverage against the official App Store Connect API documentation. It is intentionally product-oriented: it names what users can do today, what is missing, and which additions should come first.
 
@@ -18,7 +19,7 @@ P0 additions:
 - App Clips, background assets, app tags, routing app coverages, and customer review summaries.
 
 P1 additions:
-- Webhook receiver-side signature verification, event payload decoder, and triage resources/prompts.
+- Hosted webhook receiver templates and reusable triage resources/prompts.
 - Merchant IDs and Pass Type IDs under provisioning.
 - Analytics/customer-review summarization and metric recommendation ergonomics.
 
@@ -29,8 +30,8 @@ P1 additions:
 | Essentials: auth, errors, paging, uploads, rate limits | Partial | P1 | `auth` | API key inventory/revocation helpers |
 | App Store app metadata and release operations | Partial | P0 | `apps`, `accessibility`, `versions`, `app_info`, `pricing`, `app_events`, `screenshots`, `custom_pages`, `ppo`, `promoted`, `review_attachments`, `reviews` | App Clips; background assets; app tags; routing app coverages; customer review summary endpoint |
 | TestFlight builds, testers, groups, and beta app review | Partial | P0 | `builds`, `build_processing`, `build_beta`, `beta_groups`, `beta_feedback`, `beta_testers`, `beta_app`, `pre_release`, `beta_license` | beta recruitment criteria; beta app clip invocation/localization APIs |
-| Webhook notifications | Covered | P2 | `webhooks` | OpenAPI drift checks and receiver-side helper ergonomics |
-| Webhook notification receiver resources | Missing | P1 | none | signature verification helpers; event payload decoder; prompt/resource templates for event triage |
+| Webhook notifications | Covered | P2 | `webhooks` | OpenAPI drift checks and hosted receiver examples |
+| Webhook notification receiver resources | Partial | P1 | `webhooks` | hosted receiver server templates; prompt/resource templates for event triage |
 | In-app purchases, subscriptions, and offers | Covered | P2 | `iap`, `subscriptions`, `offer_codes`, `winback`, `intro_offers`, `promo_offers` | OpenAPI drift checks and schema tightening |
 | Provisioning and identifiers | Partial | P1 | `provisioning` | merchant IDs; pass type IDs |
 | Users, access, and sandbox testers | Partial | P2 | `users`, `sandbox` | API key inventory helpers; API key revocation workflow |
@@ -43,7 +44,7 @@ P1 additions:
 
 1. Add `--read-only` runtime guard so static and live validation can run safely in production-like MCP hosts.
 2. Update `AppsWorker` for app-level `accessibilityUrl` if Apple keeps it as a separate app metadata field outside declaration resources.
-3. Add webhook receiver helpers: signature verification, event payload decoder, and triage prompts/resources.
+3. Add reusable webhook receiver playbooks and optional hosted receiver templates around the new local helper tools.
 4. Add merchant/pass identifiers, App Clips, background assets, Game Center, and alternative distribution as larger domain workers.
 
 ## Safety Notes

ASC-OPENAPI-COVERAGE-GENERATED.md

@@ -31,13 +31,13 @@ Unclassified paths: 0
 | Essentials: auth, errors, paging, uploads, rate limits | Partial | P1 | 0 | 0 | `auth` | Core runtime behavior is covered; OpenAPI drift is now generated from Apple's official specification. |
 | Provisioning and identifiers | Partial | P1 | 32 | 49 | `provisioning` | Core signing automation exists; Wallet and Apple Pay identifiers are useful next additions. |
 | Reporting, analytics, metrics, and diagnostics | Partial | P1 | 47 | 56 | `analytics`, `metrics` | Read-heavy workflows are safe and valuable; summaries and recommendations are high UX leverage. |
-| Webhook notification receiver resources | Missing | P1 | 0 | 0 | none | The App Store Connect management API is covered; receiver-side helpers are local MCP value-add and should not call Apple. |
+| Webhook notification receiver resources | Partial | P1 | 0 | 0 | `webhooks` | Local receiver helpers are now available and remain read-only; future work can add deployable receiver templates and reusable playbooks. |
 | Xcode Cloud workflows and builds | Partial | P1 | 56 | 59 | `xcode_cloud` | Covers read-heavy CI dashboards plus start/rebuild build runs; destructive workflow/product management remains intentionally deferred. |
 | Alternative distribution | Missing | P2 | 21 | 28 | none | Region- and entitlement-sensitive APIs should be opt-in and strongly documented. |
 | Game Center | Missing | P2 | 238 | 337 | none | Large domain; should be added only after OpenAPI-driven scaffolding is in place. |
 | In-app purchases, subscriptions, and offers | Covered | P2 | 129 | 163 | `iap`, `subscriptions`, `offer_codes`, `winback`, `intro_offers`, `promo_offers` | Coverage is broad enough for production workflows; future work is mostly schema tightening and OpenAPI drift checks. |
 | Users, access, and sandbox testers | Partial | P2 | 13 | 20 | `users`, `sandbox` | User management is serviceable; API key operations should remain carefully annotated as high-risk. |
-| Webhook notifications | Covered | P2 | 6 | 8 | `webhooks` | Covers app webhooks, individual webhook reads, create/update/delete, delivery listing, redelivery, and ping testing. |
+| Webhook notifications | Covered | P2 | 6 | 8 | `webhooks` | Covers app webhooks, individual webhook reads, create/update/delete, delivery listing, redelivery, ping testing, and local receiver diagnostics. |
 
 ## Missing Apple Domains
 

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-05-08
+
+### Added
+
+- Local webhook receiver helpers: `webhooks_verify_signature`, `webhooks_parse_payload`, and `webhooks_triage_event` for HMAC validation, payload normalization, and actionable event/delivery triage without calling App Store Connect.
+
+### Changed
+
+- README worker counts, webhook tool docs, and coverage matrix now reflect 348 tools across 36 worker domains.
+
 ## [2.3.0] - 2026-05-08
 
 ### Added

README.md

@@ -29,7 +29,7 @@
 
 ## Overview
 
-**asc-mcp** is a Swift-based MCP server that bridges [Claude](https://claude.ai) (or any MCP-compatible host) with the [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi). It exposes **345 tools** across 36 worker domains, enabling you to automate your entire iOS/macOS release workflow through natural language.
+**asc-mcp** is a Swift-based MCP server that bridges [Claude](https://claude.ai) (or any MCP-compatible host) with the [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi). It exposes **348 tools** across 36 worker domains, enabling you to automate your entire iOS/macOS release workflow through natural language.
 
 ### Key capabilities
 
@@ -43,6 +43,7 @@
 - **Provisioning** — bundle IDs, devices, certificates, profiles, capabilities
 - **Marketing** — screenshots, app previews, custom product pages, A/B testing (PPO), promoted purchases
 - **Accessibility declarations** — manage App Store accessibility support declarations by device family
+- **Webhooks** — manage webhook configurations, inspect delivery diagnostics, verify signatures, parse payloads, and triage events
 - **Analytics & Metrics** — sales/financial reports, analytics reports, performance metrics, diagnostics
 - **Metadata management** — localized descriptions, keywords, What's New across all locales
 - **MCP 2025-11-25 surface** — tool annotations, output schemas for stable tools, structured JSON results, and safe result-size metadata
@@ -53,7 +54,7 @@
 ```bash
 # 1. Install via Mint
 brew install mint
-mint install zelentsov-dev/asc-mcp@v2.3.0
+mint install zelentsov-dev/asc-mcp@v2.4.0
 
 # 2. Add to Claude Code with env vars (simplest setup)
 claude mcp add asc-mcp \
@@ -85,7 +86,7 @@ Or use a JSON config file — see [Configuration](#configuration) below.
 brew install mint
 
 # Install asc-mcp from GitHub
-mint install zelentsov-dev/asc-mcp@v2.3.0
+mint install zelentsov-dev/asc-mcp@v2.4.0
 
 # Register in Claude Code
 claude mcp add asc-mcp -- ~/.mint/bin/asc-mcp
@@ -96,13 +97,13 @@ To install a specific branch or tag:
 ```bash
 mint install zelentsov-dev/asc-mcp@main      # main branch
 mint install zelentsov-dev/asc-mcp@develop    # develop branch
-mint install zelentsov-dev/asc-mcp@v2.3.0     # specific tag
+mint install zelentsov-dev/asc-mcp@v2.4.0     # specific tag
 ```
 
 To update to the latest version:
 
 ```bash
-mint install zelentsov-dev/asc-mcp@v2.3.0 --force
+mint install zelentsov-dev/asc-mcp@v2.4.0 --force
 ```
 
 ### Option B: Build from Source
@@ -362,7 +363,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-> **Note:** Windsurf has a 100-tool limit. The server exposes 345 tools by default, so you must use `--workers` to select a subset. See [Worker Filtering](#worker-filtering) below.
+> **Note:** Windsurf has a 100-tool limit. The server exposes 348 tools by default, so you must use `--workers` to select a subset. See [Worker Filtering](#worker-filtering) below.
 
 </details>
 
@@ -371,7 +372,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ### Worker Filtering
 
-The server exposes **345 tools** across 36 worker domains. Some MCP clients impose a tool limit (e.g., Windsurf caps at 100). Use `--workers` to enable only the workers you need:
+The server exposes **348 tools** across 36 worker domains. Some MCP clients impose a tool limit (e.g., Windsurf caps at 100). Use `--workers` to enable only the workers you need:
 
 ```bash
 # Only load apps, builds, and version lifecycle tools
@@ -397,7 +398,7 @@ asc-mcp --read-only
 asc-mcp --read-only --workers apps,builds,reviews,analytics
 ```
 
-In this mode, read tools such as `*_list`, `*_get`, `*_search`, `*_status`, `auth_*`, analytics, and metrics remain available. Tools that can create, update, upload, submit, release, delete, revoke, clear, cancel, or otherwise mutate App Store Connect are blocked before their worker handler runs. `company_switch` remains available because it changes only the local active company context.
+In this mode, read tools such as `*_list`, `*_get`, `*_search`, `*_status`, `*_verify`, `*_parse`, `*_triage`, `auth_*`, analytics, and metrics remain available. Tools that can create, update, upload, submit, release, delete, revoke, clear, cancel, or otherwise mutate App Store Connect are blocked before their worker handler runs. `company_switch` remains available because it changes only the local active company context.
 
 ### OpenAPI Drift Tooling
 
@@ -425,7 +426,7 @@ The generated report records Apple spec metadata, path and operation counts, dom
 | `auth` | `auth_` | 4 | JWT token tools |
 | `apps` | `apps_` | 9 | App listing, metadata, localizations |
 | `accessibility` | `accessibility_` | 6 | App Store accessibility declarations |
-| `webhooks` | `webhooks_` | 8 | Webhook notifications and deliveries |
+| `webhooks` | `webhooks_` | 11 | Webhook notifications, delivery diagnostics, and receiver helpers |
 | `xcode_cloud` | `xcode_cloud_` | 30 | Xcode Cloud products, workflows, build runs, artifacts, issues, test results, and SCM |
 | `builds` | `builds_` | 4 | Build management |
 | `build_processing` | `builds_get_processing_*`, `builds_update_encryption`, `builds_check_readiness` | 4 | Build states, encryption |
@@ -464,7 +465,7 @@ When connected to an LLM client, tool definitions consume context tokens. Here's
 
 | Configuration | Tools | ~Tokens |
 |---|---:|---:|
-| All workers (default) | 345 | **~39,000** |
+| All workers (default) | 348 | **~39,400** |
 | Release workflow: `apps,builds,versions,reviews` | ~57 | ~7,000 |
 | Monetization: `apps,iap,subscriptions,pricing` | ~78 | ~9,000 |
 | TestFlight: `apps,builds,beta_groups,beta_testers` | ~56 | ~6,000 |
@@ -473,11 +474,11 @@ When connected to an LLM client, tool definitions consume context tokens. Here's
 
 **Heaviest workers:** Xcode Cloud (30 tools), Subscriptions (29 tools), InAppPurchases (24 tools), Provisioning (17 tools), Screenshots (16 tools).
 
-For Claude (200K context) ~39K tokens is about 20% of the window. For clients with smaller context windows, use `--workers` to reduce the footprint.
+For Claude (200K context) ~39.4K tokens is about 20% of the window. For clients with smaller context windows, use `--workers` to reduce the footprint.
 
 ## Available Tools
 
-**345 tools** organized across 36 worker domains (use `--workers` to filter — see [Worker Filtering](#worker-filtering)):
+**348 tools** organized across 36 worker domains (use `--workers` to filter — see [Worker Filtering](#worker-filtering)):
 
 <details>
 <summary><strong>Company Management</strong> — 3 tools</summary>
@@ -534,7 +535,7 @@ For Claude (200K context) ~39K tokens is about 20% of the window. For clients wi
 </details>
 
 <details>
-<summary><strong>Webhook Notifications</strong> — 8 tools</summary>
+<summary><strong>Webhook Notifications</strong> — 11 tools</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -546,6 +547,9 @@ For Claude (200K context) ~39K tokens is about 20% of the window. For clients wi
 | `webhooks_list_deliveries` | List delivery attempts |
 | `webhooks_redeliver` | Redeliver an existing delivery |
 | `webhooks_ping` | Send a test ping |
+| `webhooks_verify_signature` | Verify `x-apple-signature` against the exact raw payload body |
+| `webhooks_parse_payload` | Parse and normalize a raw webhook notification payload |
+| `webhooks_triage_event` | Produce an actionable triage plan for webhook events or delivery failures |
 
 </details>
 

SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Supported |
 |---------|-----------|
+| 2.4.x   | Yes       |
 | 2.3.x   | Yes       |
 | 2.2.x   | Yes       |
 | 2.1.x   | Yes       |

Sources/asc-mcp/Core/ASCCoverageInventory.swift

@@ -134,21 +134,24 @@ enum ASCCoverageInventory {
                 "send webhook ping"
             ],
             missingCapabilities: [],
-            notes: "Covers app webhooks, individual webhook reads, create/update/delete, delivery listing, redelivery, and ping testing."
+            notes: "Covers app webhooks, individual webhook reads, create/update/delete, delivery listing, redelivery, ping testing, and local receiver diagnostics."
         ),
         ASCCoverageArea(
             name: "Webhook notification receiver resources",
             appleDocumentationURL: "https://developer.apple.com/documentation/appstoreconnectapi/webhook-notifications",
-            status: .missing,
+            status: .partial,
             priority: .p1,
-            workerKeys: [],
-            coveredCapabilities: [],
-            missingCapabilities: [
-                "receiver-side signature verification helpers",
+            workerKeys: ["webhooks"],
+            coveredCapabilities: [
+                "receiver-side x-apple-signature verification",
                 "webhook event payload decoder",
-                "prompt/resource templates for event triage"
+                "event and delivery triage recommendations"
+            ],
+            missingCapabilities: [
+                "hosted receiver server templates",
+                "MCP prompt/resource templates for reusable event playbooks"
             ],
-            notes: "The App Store Connect management API is covered; receiver-side helpers are local MCP value-add and should not call Apple."
+            notes: "Local receiver helpers are now available and remain read-only; future work can add deployable receiver templates and reusable playbooks."
         ),
         ASCCoverageArea(
             name: "In-app purchases, subscriptions, and offers",

Sources/asc-mcp/Core/Application.swift

@@ -45,7 +45,7 @@ public func runApplication(options: AppRuntimeOptions = AppRuntimeOptions()) asy
         - auth_* — authentication
         - apps_* — app management and metadata
         - accessibility_* — App Store accessibility declarations by device family
-        - webhooks_* — webhook notifications and delivery diagnostics
+        - webhooks_* — webhook notifications, delivery diagnostics, signature verification, payload parsing, and triage
         - xcode_cloud_* — Xcode Cloud products, workflows, builds, artifacts, issues, test results, and SCM resources
         - builds_* — build management
         - app_versions_* — version lifecycle (create, submit, release)

Sources/asc-mcp/Core/ServerVersion.swift

@@ -1,5 +1,5 @@
 import Foundation
 
 enum ServerVersion {
-    static let current = "2.3.0"
+    static let current = "2.4.0"
 }