@postman/postman-plugin 0.2.2 → 0.4.0

package/skills/postman-mcp-server/SKILL.md

@@ -1,71 +1,65 @@
 ---
 name: postman-mcp-server
-description: Postman concepts and MCP tool guidance. Loaded when working with Postman MCP tools to make better decisions about tool selection and workarounds.
-user-invocable: false
+description: Use when working through Postman MCP tools to inspect or change workspace resources, choose a targeted operation, or handle MCP limitations. Supports hosted workflows when the CLI is unavailable and distinguishes tool completion from a usable result. Use for requests such as "use Postman MCP to inspect this collection".
 ---
 
-# Postman Knowledge
+# Postman MCP Server
 
-Reference for Postman concepts and MCP tool selection. Use this context when working with Postman MCP tools to make better decisions.
+MCP exposes workspace resources directly to an agent. Existing collections,
+specs, examples, and environments provide maintained API knowledge; fetching
+the relevant entity preserves that context when a local CLI workflow is not
+available. For repository edits and Git review, prefer the local workflows in
+**api-engineer** and **bootstrap** when available.
 
-See `references/setup.md` for how to to setup postman mcp server and auth.
+Each tool definition exposed to the model consumes context whenever it is
+included in a request. Prefer the smallest available toolset that covers the
+task; expanding to every tool can crowd out the API evidence needed to reason.
+When exposed, call `getEnabledTools` to inspect the active toolset before
+diagnosing a missing operation. Otherwise use the host's discovered tools and
+report that limitation. Do not infer availability from reference tool names or
+assume a client can switch a route pinned to a specific MCP endpoint.
 
-## Core Concepts
+1. Select tools from the connected server's actual surface. Tool availability
+   varies by mode; a name listed in a reference is not proof it is exposed.
+   Use [setup](references/setup.md) for connection/auth failures and
+   [limitations](references/mcp-limitations.md) when an operation is missing
+   or behaves differently from the CLI.
+2. Search to locate an entity, then fetch enough detail to work on it.
+   `searchPostmanElements` finds candidates; collection, spec, and workspace
+   detail tools establish IDs, ownership, and content. A search preview is
+   insufficient evidence for replacing a collection or declaring an API absent.
+3. Match the mutation to the intended scope. Request-level updates preserve
+   unrelated collection content; whole-collection replacement requires the
+   current complete object. A workspace is a container and access boundary,
+   not a reason to create duplicate resources whenever a new task begins.
+4. Preserve the source of truth when synchronizing. Spec-to-collection
+   generation reuses the interface, while collection-to-spec sync carries
+   changes in the other direction. Choose from the intended contract rather
+   than overwriting whichever artifact is easiest to reach. An asynchronous
+   acceptance response needs a completed task result before claiming sync.
+5. Treat publication separately from editing. A collection example can feed
+   docs and a classic mock, but neither becomes publicly accessible merely
+   because it exists. Apply the user's intended audience and authorization
+   before publishing docs or mocks, or changing shared resources.
 
-- **Collection:** A group of API requests organized in folders. The primary unit of work in Postman. Contains requests, examples, tests, and documentation.
-- **Environment:** Key-value pairs (variables) scoped to a context (dev, staging, prod). Used to swap base URLs, auth tokens, and config without changing requests.
-- **Workspace:** Container for collections, environments, and specs. Can be personal, team, or public.
-- **Spec (Spec Hub):** An OpenAPI or AsyncAPI definition stored in Postman. Can generate collections and stay synced.
-- **Request:** A single API call definition (method, URL, headers, body, tests).
-- **Response:** A saved example response for a request. Used by mock servers and documentation.
-- **Folder:** A grouping within a collection, typically by resource (e.g., "Users", "Orders").
-- **Tags:** Labels on collections for categorization and search.
-- **Monitor:** A scheduled collection runner that checks API health.
-- **Mock Server:** A fake API that serves example responses from a collection.
+Read the reference for the branch being used:
 
-## Decision Guide
+| Task | Reference and decision it supports |
+| --- | --- |
+| Locate an API | [Search](references/search.md): narrow candidates to the intended resource |
+| Generate or synchronize artifacts | [Sync](references/sync.md): choose source and track completion |
+| Serve saved examples | [Mock](references/mock.md): classic collection mocks; for CLI Code Mocks use **api-mocking** |
+| Execute saved assertions | [Test](references/test.md): distinguish run completion from failures |
+| Improve or publish docs | [Docs](references/docs.md): fill contract gaps and verify reader access |
+| Requested security review | [Security](references/security.md): assess concrete API risks |
+| Product how-to questions | [Learning Center](references/learn.md): product documentation search when exposed |
 
-| Goal | Approach |
-|------|----------|
-| Push code changes to Postman | Create/update spec in Spec Hub, then sync to collection |
-| Consume a Postman API | Read collection + generate client code |
-| Find an API | Use `searchPostmanElements`, then drill into details |
-| Test an API | Run collection with `runCollection` |
-| Create a fake API for frontend | Create mock server from collection with examples |
-| Document an API | Analyze collection completeness, fill gaps, optionally publish |
-| Audit API security | Run security checks against spec or collection |
-| Learn how to use a Postman feature | Search Postman docs with `searchLearningCenter` (Full mode) |
+## Verification
 
-## MCP Tool Selection
+State the active toolset as observed through `getEnabledTools`, or identify the
+host discovery evidence used when that tool is unavailable. Report any operation
+the connected surface could not perform instead of claiming it succeeded.
 
-**Workspace operations:** `getWorkspaces`, `getWorkspace`, `createWorkspace`
-**Collection CRUD:** `getCollections`, `getCollection`, `createCollection`, `putCollection`, `patchCollection`, `deleteCollection`
-**Request/Response:** `getCollectionRequest`, `createCollectionRequest`, `updateCollectionRequest`, `getCollectionResponse`, `createCollectionResponse`, `updateCollectionResponse`
-**Folder management:** `getCollectionFolder`, `createCollectionFolder`, `updateCollectionFolder`
-**Spec Hub:** `getAllSpecs`, `getSpec`, `createSpec`, `getSpecDefinition`, `updateSpecFile`, `getSpecFiles`
-**Sync:** `generateCollection`, `syncCollectionWithSpec`, `syncSpecWithCollection`
-**Environments:** `getEnvironments`, `getEnvironment`, `createEnvironment`, `putEnvironment`
-**Mocks:** `getMocks`, `getMock`, `createMock`, `publishMock`, `unpublishMock`
-**Tests:** `runCollection`
-**Docs:** `publishDocumentation`, `unpublishDocumentation`
-**Search:** `searchPostmanElements` , `getTaggedEntities`
-**Learning Center:** `searchLearningCenter` (Full mode only — searches Postman product docs for how-to guidance)
-**User:** `getAuthenticatedUser`
-
-See `references/mcp-limitations.md` for known limitations and workarounds.
-
-## Workflows
-
-Each reference below is a full MCP-tool workflow for one goal — the tool
-call sequence, what to present at each step, and error handling. Reach for
-one once the Decision Guide above has picked a goal; they assume MCP tools
-only, no `postman` CLI.
-
-- `references/setup.md` — first-run auth (OAuth or API key) and workspace verification.
-- `references/search.md` — discover APIs across workspaces with `searchPostmanElements`.
-- `references/sync.md` — create/update collections from specs, or sync a spec from collection changes.
-- `references/mock.md` — create a mock server from a collection or spec.
-- `references/test.md` — run collection tests and diagnose failures.
-- `references/docs.md` — generate, improve, and publish API documentation.
-- `references/security.md` — audit a spec or collection against the OWASP API Top 10.
-- `references/learn.md` — search the Postman Learning Center for how-to guidance.
+Report the resource and observed result: assertions for a run, completed sync
+for a generated artifact, or the reachable URL and visibility for publication.
+Tool success alone does not establish any of those outcomes.

package/skills/postman-mcp-server/references/docs.md

@@ -1,6 +1,5 @@
 ---
 description: Generate, improve, and publish API documentation from Postman collections.
-allowed-tools: Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__updateCollectionRequest, mcp__postman__publishDocumentation, mcp__postman__unpublishDocumentation, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks
 ---
 
 # API Documentation

package/skills/postman-mcp-server/references/learn.md

@@ -1,6 +1,5 @@
 ---
 description: Search the Postman Learning Center for how-to guidance, feature explanations, and suggested workflows. Use for "how do I..." questions about the Postman product.
-allowed-tools: Read, mcp__postman__searchLearningCenter, mcp__postman__getEnabledTools
 ---
 
 # Learn Postman
@@ -11,14 +10,16 @@ Use this to learn *about Postman itself* — not to search the user's own collec
 
 ## Prerequisites
 
-This workflow uses `searchLearningCenter`, which the Postman MCP Server exposes only in **Full mode**.
+Use `searchLearningCenter` when it is exposed by the connected server. Follow
+**postman-mcp-server**'s toolset inspection guidance before diagnosing a missing
+tool; a remembered mode-to-tool mapping is not evidence of current availability.
+The route's MCP endpoint determines its configured surface. `POSTMAN_MCP_MODE`
+is not read by this plugin's routes and cannot switch that surface.
 
-The mode is fixed by the endpoint in each route's MCP config, not by the environment. A route pinned to `https://mcp.postman.com/mcp` has the tool; a route pinned to `https://mcp.postman.com/minimal` does not. Read it off the route's own MCP config rather than inferring it from the agent's name — which endpoint an agent gets is a per-route product decision, and new routes are added. **`POSTMAN_MCP_MODE` is not read on any route** — never tell the user to set or unset it to change the tool set.
-
-- If MCP tools aren't available at all, follow `references/setup.md` to connect the Postman MCP Server.
-- If `searchLearningCenter` is missing, call `getEnabledTools` to confirm the active tool set, then split on which endpoint the route is pinned to. On a `/minimal` route it is absent by design and the user cannot change it from the client: say the Learning Center tool isn't part of that route's tool set and point them at https://learning.postman.com to search directly. On a `/mcp` route its absence is not a mode problem — the server isn't connected as configured: follow `references/setup.md` to reconnect it.
-
-Do not answer a "how do I..." question from memory when the tool is unavailable. Cite only URLs the tool returned, or send the user to the Learning Center.
+If no MCP tools are available, follow `references/setup.md`. If only the learning
+tool is absent, use an available web search/browser to read the official Learning
+Center and cite the pages actually consulted. Without either capability, report
+the limitation and link the Learning Center rather than inventing product steps.
 
 ## Workflow
 
@@ -68,6 +69,6 @@ To create a mock server in Postman:
 ## Error Handling
 
 - **MCP not configured:** Follow `references/setup.md` to connect the Postman MCP Server.
-- **`searchLearningCenter` unavailable:** Confirm with `getEnabledTools`. Expected on any route pinned to the `minimal` endpoint — say the tool isn't in that route's tool set and point the user at https://learning.postman.com. On a `/mcp` route: follow `references/setup.md` to reconnect it.
+- **`searchLearningCenter` unavailable:** Use the toolset inspection and official-documentation fallback under Prerequisites.
 - **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **No results:** "Nothing matched in the Learning Center. Try rephrasing with the Postman feature name, or ask about a more specific step."

package/skills/postman-mcp-server/references/mock.md

@@ -1,6 +1,5 @@
 ---
 description: Create Postman mock servers for frontend development. Generates missing examples, provides integration config.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__createCollectionResponse, mcp__postman__createSpec, mcp__postman__generateCollection, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__getSpecCollections, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getMocks, mcp__postman__getMock, mcp__postman__createMock, mcp__postman__publishMock, mcp__postman__unpublishMock
 ---
 
 # Create Mock Servers

package/skills/postman-mcp-server/references/search.md

@@ -1,6 +1,5 @@
 ---
 description: Discover APIs across your Postman workspaces. Ask natural language questions about available endpoints and capabilities.
-allowed-tools: Read, Glob, Grep, mcp__postman__searchPostmanElements, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getTaggedEntities, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__getSpecDefinition
 ---
 
 # Discover APIs

package/skills/postman-mcp-server/references/security.md

@@ -1,6 +1,5 @@
 ---
 description: Security audit your APIs against OWASP API Top 10. Finds vulnerabilities and provides remediation guidance.
-allowed-tools: Read, Edit, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__getEnvironment, mcp__postman__putEnvironment, mcp__postman__updateCollectionRequest, mcp__postman__updateCollectionResponse
 ---
 
 # API Security Audit

package/skills/postman-mcp-server/references/setup.md

@@ -1,6 +1,5 @@
 ---
 description: Set up Postman MCP Server. Authenticate via OAuth or API key, verify connection, select workspace.
-allowed-tools: mcp__postman__authenticate, mcp__postman__complete_authentication, mcp__postman__getAuthenticatedUser, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getAllSpecs
 ---
 
 # First-Run Configuration

package/skills/postman-mcp-server/references/sync.md

@@ -1,6 +1,5 @@
 ---
 description: Sync Postman collections with your API code. Create collections from specs, push updates, keep everything in sync.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__createSpec, mcp__postman__updateSpecFile, mcp__postman__generateCollection, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks, mcp__postman__createEnvironment, mcp__postman__createCollectionRequest, mcp__postman__updateCollectionRequest, mcp__postman__createCollectionFolder, mcp__postman__createCollectionResponse
 ---
 
 # Sync Collections

package/skills/postman-mcp-server/references/test.md

@@ -1,6 +1,5 @@
 ---
 description: Run Postman collection tests, analyze results, diagnose failures, and suggest fixes.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__runCollection, mcp__postman__getEnvironments, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__updateCollectionRequest, mcp__postman__updateCollectionResponse
 ---
 
 # Run Collection Tests

package/skills/variables/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: variables
+description: Use when parameterizing requests across environments, choosing variable scopes, chaining values in scripts, or referencing credentials without committing or exposing them. Keeps one reusable collection while separating target configuration from secret values. Use for requests such as "where should I put this API key".
+---
+
+# Variables
+
+Variables let one maintained collection run against different targets without
+forking its requests. Scope determines which value wins; secret references
+allow the same files to be shared without sharing credential values.
+
+1. Put API defaults in collection variables and target-specific values, such
+   as `base_url`, in an environment. Parameterize values that actually vary;
+   a stable literal need not become another configuration choice. Reference
+   values as `{{key}}` in URLs, headers, parameters, or bodies.
+2. Resolve surprises through precedence: local script values override
+   iteration data, then environment, collection, and global values. A correct
+   environment file can still lose to a row or script override. Values can
+   reference other variables and resolve at send time, so inspect the chain
+   rather than just the final request field.
+3. Use runtime values for chaining responses into later requests. Choose
+   `pm.environment` or `pm.collectionVariables` when the scope is intentional;
+   `pm.variables.get` reads across scopes, and `pm.variables.set` holds a local
+   value for the current run. For transient sensitive values, avoid persisting
+   them to an environment or logging them.
+4. Store durable credentials in the shared vault and commit references.
+   `type: secret` alone masks the UI but still leaves a literal YAML value
+   readable. **collection-schema-v3**'s environment reference describes the
+   file schema; command-specific `-h` supplies supported vault operations.
+
+For non-sensitive target configuration:
+
+```bash
+postman environment new "Staging"
+postman environment var set base_url https://staging.example.com \
+  --environment "postman/environments/Staging.environment.yaml"
+```
+
+For a secret, have the user supply the value through the CLI's masked prompt,
+not through agent context or a literal command argument:
+
+```bash
+postman secret create STRIPE_API_KEY --workspace <workspace-id>
+postman environment var set api_key --secret-id <secret-id> --vault-id <vault-id> \
+  --environment "postman/environments/Staging.environment.yaml"
+```
+
+The environment then carries the vault/secret IDs rather than the value.
+Secret resolution and permission to view the secret are distinct; a teammate's
+ability to run a request need not expose the credential to them. Use
+**bootstrap** when the vault operation needs unresolved authentication.
+
+## Verification
+
+Run `postman environment lint <path> --fail-severity warning` to fail on
+warnings as well as errors in the saved environment. Lint checks the artifact;
+it does not prove that the session can resolve a vault secret. Verify resolution
+with an appropriate authenticated request and a contract-derived assertion,
+keeping credentials out of output. An unresolved-reference or authorization
+failure needs investigation, not a claim that the secret worked.
+Report the selected environment and scope
+or reference that supplies the value; a masked display alone does not prove
+that the committed file contains no literal secret.

package/skills/webhook-testing/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: webhook-testing
+description: Capture, forward to localhost, replay, and validate webhook deliveries using a reusable public URL. Keep sender configuration across debugging sessions and record arrivals even while local forwarding is stopped, helping distinguish delivery failures from local connectivity issues. Use for implementing or debugging incoming handlers and testing webhooks an API sends, whether or not Postman is mentioned. Example requests include "get payment events to localhost," "inspect a webhook delivery," and "replay an event after a fix"; these illustrate intent, not an exhaustive list or exact phrases to match.
+---
+
+# Webhook Testing
+
+`postman webhook` gives a sender a hosted URL,
+`https://<webhookId>.webhook.pstmn.io`, that records every request it gets,
+with the raw headers and body as they were sent, and forwards each one to a
+port on this machine. You don't need a separate tunnel. Two properties shape
+how to use it:
+
+- **Reuse the URL across debugging sessions.** It survives new sessions, pause
+  and start, so the sender is registered once. Reuse a webhook when the user
+  names one or says the sender already posts to one. Use `list` to resolve that
+  reference; ask only if the available context still leaves multiple plausible choices.
+  Create a new one when a new endpoint is needed. Each new webhook is another
+  URL to register and a second event history.
+- **Every request is recorded,** including requests that arrive while nothing
+  is forwarding. `requests describe` shows a delivery exactly as it was sent.
+  After a fix, `requests replay` sends it again, so you don't need the sender
+  to fire it again.
+
+The command is singular, and every subcommand needs a signed-in session. Run what you need,
+and read `bootstrap` only if a command fails with a setup error such as `Authentication required`.
+When all you have is the URL, its subdomain is the webhook id.
+
+For capture or inspection alone, create or reuse a webhook and inspect its
+recorded requests; no local service or forwarding to a local port is needed.
+
+Use replays and [scripts](reference/webhook_scripts.md) to validate incoming events.
+
+## Get a sender reaching localhost
+
+When the task is to reach a local handler, check the path from the public URL
+meant to be forwarded to the local service:
+
+1. **Make sure the route exists.** A URL that forwards to a local service with no
+   matching route only ever returns 404. Check the local service for a handler for
+   this event. Add a missing handler when implementing the receiver is part
+   of the task. Senders retry, and replay re-sends an identical request, so
+   deduplicate using the sender's stable event identifier where available.
+   Acknowledge valid, authenticated events that the handler intentionally
+   ignores with a 2xx to avoid unnecessary retries; malformed or
+   unauthenticated requests still need rejection.
+2. **Reuse the existing webhook or create a new endpoint.** To create one,
+   use `postman webhook create --title <name>`. When a new endpoint is clearly
+   needed, creating it directly avoids an unnecessary discovery step.
+3. **Start the local service, then forward to its port** with
+   `postman webhook forward <webhookId> <port>`. `forward` runs until it's
+   stopped, so run it in the background. For stopping the forwarding process,
+   see [Forwarding lifecycle](reference/forwarding.md).
+4. **Send one request to the URL, at the route's path.** Check that a 2xx came
+   back and that the handler logged the request. `requests list` shows whether
+   the request reached the webhook at all, which separates a wrong URL from a
+   forwarding or routing problem.
+
+For a connectivity task, one successful probe demonstrates that the tested
+path reaches the handler. Sender compatibility and handler correctness need
+evidence from actual sender deliveries and relevant scenarios.
+
+## Gotchas / Notes
+
+- **Build the webhook script's test event from the sender's contract, not from your handler.**
+  A payload written to match the handler you just wrote only proves the two
+  agree with each other. Take it from the sender's documented event schema.
+  Better, use a real delivery: send one from the sender's test mode (such as
+  `stripe trigger <event>` or a GitHub redelivery), then replay that recorded
+  request as you iterate.
+- **A permission error needs workspace context.** Check the selected workspace
+  and the account's access. A cloned repository may point to a workspace this
+  account cannot use. If the intended accessible workspace is known, pass
+  `-w`; otherwise ask which workspace to use. Creating another workspace does
+  not grant access to the existing one.
+- **Some old signed events fail verification on replay, by design.** Stripe
+  (`t=` in `Stripe-Signature`) and Slack (`X-Slack-Request-Timestamp`) sign a
+  timestamp, and their SDKs reject one older than about five minutes.
+  Send a fresh event instead of loosening verification. GitHub's signature has no
+  timestamp, so its replays still verify.
+- **Confirm before `delete`.** It's permanent, and a sender still registered
+  to the URL starts failing. Replay also reaches application code, so account
+  for the handler's side effects when choosing which delivery to resend.
+
+## Handing over
+
+For endpoint setup, leave the webhook active so the user can point a sender
+at it. For a completed investigation, choose the final state based on whether
+the sender still needs the endpoint. Forwarding stops when the `forward`
+process does; while the webhook remains active, arrivals are recorded and
+can be replayed. Give the user:
+
+- the URL with the route's path;
+- for local forwarding, the two commands that start the loop again: start
+  the local service, then `postman webhook forward <webhookId> <port>`;
+- any changes made to the local service;
+- what was verified: the captured delivery or the response and handler receipt
+  for a forwarding test.
+
+To validate deliveries automatically with a `pm.test` script, see
+[reference/webhook_scripts.md](reference/webhook_scripts.md). To test the
+webhooks your own API sends, with a Postman webhook as the subscriber, see
+[reference/outbound_webhooks.md](reference/outbound_webhooks.md).

package/skills/webhook-testing/reference/forwarding.md

@@ -0,0 +1,10 @@
+# Forwarding lifecycle
+
+`postman webhook forward <webhookId> <port>` runs until stopped. To stop a
+background forwarding process, use
+`pkill -INT -f "webhook forward <webhookId>"`. `kill $!` may reach only the
+`postman` launcher and leave forwarding running.
+
+Stopping forwarding leaves the webhook available to record deliveries. Start
+forwarding again when the local service is ready, then replay a captured
+request when the task needs it.

package/skills/webhook-testing/reference/outbound_webhooks.md

@@ -0,0 +1,25 @@
+# Testing the webhooks your API sends
+
+Here the Postman webhook stands in for a subscriber. Create one with
+`postman webhook create`, then register its URL as the subscriber endpoint in
+your app, through its config or your subscription API. Trigger the action that
+emits the event, with `postman request` or a collection that already covers it
+(see the `api-testing` skill). Find the delivery with `requests list` and read
+it with `requests describe`.
+
+Check the delivery against the event contract you publish:
+
+- the event type and the body's shape;
+- the signature header, recomputed from the raw body with the secret your
+  subscriber holds;
+- the delivery or idempotency id, which should be unique per event and stay
+  the same across retries.
+
+Put those checks in an `onEvent` script so each delivery gets a test report;
+see [webhook_scripts.md](webhook_scripts.md). Its last section covers checking
+your own signature scheme.
+
+To test retries, the subscriber has to fail. Either set the webhook's routing to
+respond with a 5xx in the Postman app (routing isn't a CLI command), or forward
+to a local endpoint that returns one. Check that `requests list` records the
+failing response status before you read the repeated deliveries as retries.

package/skills/webhook-testing/reference/webhook_scripts.md

@@ -0,0 +1,163 @@
+# Webhook scripts
+
+Recipes for the `onEvent` script that `postman webhook scripts set` uploads.
+Each delivery runs the script in a fresh Postman sandbox, with the incoming
+request in `pm.request`. `pm.test` results appear in
+`postman webhook requests describe <webhookId> <requestId>`, and the
+`console.log` output appears with `--verbose`.
+
+```bash
+postman webhook scripts set <webhookId> ./webhooks/github-on-event.js --event onEvent
+```
+
+## Contents
+
+- [How webhook scripts behave](#how-webhook-scripts-behave)
+- [What a script can use](#what-a-script-can-use)
+- [Asserting on the payload](#asserting-on-the-payload)
+- [Signature checks](#signature-checks): GitHub, Stripe, Slack, any HMAC
+
+## How webhook scripts behave
+
+- **`onEvent`** runs when a request arrives, before Postman forwards or
+  responds. Use it to validate the payload, verify the signature, or modify
+  the request. **`onResponse`** runs after Postman has responded to the
+  sender. Use it for logging and follow-up work from your local responder
+  or the configured forwarding endpoint.
+- **The file in the repo is the only copy you can read.** The CLI has
+  `scripts set` but no command that reads a script back, and a second `set`
+  replaces the first. Commit the script beside the handler it guards, and set
+  it again after you edit it. The file can be JavaScript or TypeScript.
+- **No state carries over between deliveries.** A script can't remember which
+  event ids it has already seen, so test duplicate handling in the handler, by
+  replaying a request twice.
+- **Secrets come from the linked environment.** Read a signing secret with
+  `pm.environment.get` and never write it into the file. An environment is
+  linked to a webhook in its settings in the Postman app. See the `variables`
+  skill for where a secret belongs.
+- **Results are per delivery.** The console output that `--verbose` shows is
+  capped at 25 KB per event.
+- **A script is a test, not your handler's guard.** Postman doesn't document
+  that a failing `pm.test` stops the request from being routed. Your handler
+  verifies signatures itself, whatever the script reports.
+
+## What a script can use
+
+| Available | Not available |
+| --- | --- |
+| `pm.request.headers.get(name)`, `pm.request.body.raw` | `pm.globals`, `pm.collectionVariables`, `pm.iterationData` |
+| `pm.test`, `pm.expect` | `pm.execution.setNextRequest`, `pm.visualizer` |
+| `pm.environment.get`, from the environment linked to the webhook | State that lasts beyond one delivery |
+| `require("crypto-js")` and other packages, from the Package Library, npm or JSR | |
+| `pm.execution.runRequest`, to run a saved collection request | |
+
+Parse and hash `pm.request.body.raw`. Postman keeps the body exactly as the
+sender sent it, and every signature scheme below is computed over those exact
+bytes. A body that was parsed and serialized again fails the check even when
+the JSON is the same.
+
+## Asserting on the payload
+
+Write down the contract the handler depends on. A test fails on the first
+delivery that breaks it, instead of when the handler happens to crash.
+
+```javascript
+// Just a reference based on expected payload, it can be of a different data type as well.
+const event = JSON.parse(pm.request.body.raw);
+
+pm.test("is a JSON event with an id and a type", function () {
+    pm.expect(event).to.have.property("id").that.is.a("string");
+    pm.expect(event).to.have.property("type").that.is.a("string");
+});
+
+pm.test("is an event this handler subscribes to", function () {
+    pm.expect(["payment_intent.succeeded", "payment_intent.payment_failed"])
+        .to.include(event.type);
+});
+```
+
+## Signature checks
+
+Postman also has signature-verification presets for Stripe, GitHub and Slack
+in the Postman app. Use a script when you want the check in a file that can be
+reviewed, or when the provider has no preset. Read the secret from the linked
+environment. A secret pasted into the script ends up in the repo and in the
+webhook's configuration.
+
+### GitHub
+
+`X-Hub-Signature-256` is `sha256=` followed by the hex HMAC-SHA256 of the raw
+body. There's no timestamp, so a replayed delivery still verifies.
+
+```javascript
+const CryptoJS = require("crypto-js");
+
+const secret = pm.environment.get("github_webhook_secret");
+const expected = "sha256=" +
+    CryptoJS.HmacSHA256(pm.request.body.raw, secret).toString(CryptoJS.enc.Hex);
+
+pm.test("GitHub signature matches the body", function () {
+    pm.expect(pm.request.headers.get("X-Hub-Signature-256")).to.equal(expected);
+});
+```
+
+### Stripe
+
+`Stripe-Signature` is `t=<unix seconds>,v1=<hex>[,v1=<hex>…]`. Stripe signs
+`<t>.<raw body>` with the endpoint's whole `whsec_…` secret, prefix included.
+More than one `v1` appears while a secret is being rolled, and any one of them
+can match.
+
+```javascript
+const CryptoJS = require("crypto-js");
+
+const secret = pm.environment.get("stripe_webhook_secret");
+const fields = pm.request.headers.get("Stripe-Signature").split(",");
+const t = fields.find(f => f.startsWith("t=")).slice(2);
+const signatures = fields.filter(f => f.startsWith("v1=")).map(f => f.slice(3));
+const expected = CryptoJS.HmacSHA256(t + "." + pm.request.body.raw, secret)
+    .toString(CryptoJS.enc.Hex);
+
+pm.test("Stripe signature matches the body", function () {
+    pm.expect(signatures).to.include(expected);
+});
+
+pm.test("Stripe timestamp is within five minutes", function () {
+    pm.expect(Math.abs(Date.now() / 1000 - Number(t))).to.be.below(300);
+});
+```
+
+The timestamp test fails on a replay of anything older than five minutes. That
+failure is expected and doesn't mean the replay is broken.
+
+### Slack
+
+Slack signs `v0:<X-Slack-Request-Timestamp>:<raw body>` with the app's signing
+secret and sends `X-Slack-Signature: v0=<hex>`.
+
+```javascript
+const CryptoJS = require("crypto-js");
+
+const secret = pm.environment.get("slack_signing_secret");
+const ts = pm.request.headers.get("X-Slack-Request-Timestamp");
+const expected = "v0=" +
+    CryptoJS.HmacSHA256("v0:" + ts + ":" + pm.request.body.raw, secret)
+        .toString(CryptoJS.enc.Hex);
+
+pm.test("Slack signature matches the body", function () {
+    pm.expect(pm.request.headers.get("X-Slack-Signature")).to.equal(expected);
+});
+
+pm.test("Slack timestamp is within five minutes", function () {
+    pm.expect(Math.abs(Date.now() / 1000 - Number(ts))).to.be.below(300);
+});
+```
+
+### Any other HMAC scheme, including your own API's
+
+Start from the provider's documentation, or your own if you're checking the
+webhooks your API sends. Find out three things: which header carries the
+signature and any prefix it uses, exactly which bytes are signed (the body
+alone, or a timestamp or id joined to it), and whether the result is hex or
+base64. A mismatch is nearly always one of those three. Use
+`CryptoJS.enc.Base64` in place of `CryptoJS.enc.Hex` for a base64 signature.