webhook-testing

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 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.
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.