@postman/postman-plugin 0.3.0 → 0.4.1-rc.0

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.