Monitors and webhooks

This page covers two features that keep watch while Cloak Proxy is open. A monitor runs a collection on a schedule, like Postman’s monitors, keeps a history of every run, and tells you when tests start failing. The webhook receiver listens on a local port for webhook deliveries from services you’re integrating with, logs each one, answers with the response you choose, and can forward or replay them to your own server.

Create a monitor

1. Do one of these:

   • Click Monitors in the left rail, then + at the top of the sidebar (the button is disabled until you have a collection).
   • Right-click a collection in the sidebar and choose Monitor Collection.
   • Open a collection and choose More › Monitor….

   A monitor named Collection name monitor opens, set to the active environment and to run every hour.

2. Click the name and give it a clearer one, for example Petstore smoke test.

3. Choose the Collection, the Environment and how often to Run every.

4. Leave Enabled and Notify me when a run fails on. Optionally paste a Webhook on failure URL, such as a Slack incoming webhook.

5. Click Run Now to check it works.

12345

A monitor with its settings, a chart of recent runs and the run history.

1. Run Now runs the monitor immediately
2. Which collection and environment to run, and how often
3. Turn the schedule and failure notifications on or off
4. Optional webhook that gets a summary of failed runs
5. Average response time per run, green for passed and red for failed

×

Monitor settings

Setting	Default	What it does
Collection	The collection you started from	The collection to run. The whole collection runs once, in order, with its scripts and tests.
Environment	The active environment when you created the monitor	The environment to run with, or None. It doesn’t have to be the active one, so a monitor can watch production while you work in staging.
Run every	Hour	5 minutes, 15 minutes, 30 minutes, Hour, 6 hours, Day or Week.
Enabled	On	Turn off to pause the schedule. Run Now still works.
Notify me when a run fails	On	Shows a macOS notification when a run has a failed test or a request error.
Webhook on failure	Empty	A URL that gets a JSON summary of each failed run. See Failure notifications.

Monitors use your globals and Vault secrets. Each run is a single iteration with no data file, and variable changes made by scripts aren’t saved.

When monitors run

Cloak Proxy checks every 30 seconds for monitors that are due. A monitor is due when it’s Enabled and either it has never run, or the Run every interval has passed since its last run started. A monitor that’s already running isn’t started again.

Monitors run only while Cloak Proxy is open. If the Mac sleeps or the app quits, missed runs aren’t made up; the monitor runs once when it’s next due.

Monitoring around the clock

For monitoring that doesn’t depend on the app being open, run cloakctl collection run from cron, launchd or CI. See Monitor around the clock.

Run history

Every run is saved with the monitor, up to the latest 200.

• The Average response (ms) chart shows the last 50 runs as bars: green for a run that passed, red for one that failed.
• The list below it shows every run, newest first: a pass or fail icon, the date and time, then N requests · N passed · N failed · N ms avg, and the first failure in red.

A run passes when no test fails and every request was sent. In the Monitors sidebar, each monitor’s dot is green when its last run passed, red when it failed, and gray before its first run. Right-click a monitor for Run Now and Delete.

Monitors and their history are saved in monitors.json in the workspace, so they’re shared through Git with the rest of the workspace.

Failure notifications

When a run fails:

• Notify me when a run fails shows a macOS notification titled Monitor “name” failed, with the first failure as the message.
• Webhook on failure gets an HTTP POST with a JSON body. The text field is formatted for Slack incoming webhooks, and most chat tools that accept webhooks read it too.

Webhook body

{
  "text": "Cloak Proxy monitor “Petstore smoke test” failed: 6 requests, 1 failed tests, 0 errors\n• Get pet: Status code is 2xx — expected response to have status code 200 but got 500",
  "monitor": "Petstore smoke test",
  "succeeded": false,
  "failures": [
    "Get pet: Status code is 2xx — expected response to have status code 200 but got 500"
  ]
}

Field	Contents
text	A one-line summary, then up to 10 failures as bullet points.
monitor	The monitor’s name.
succeeded	Always false, because only failed runs send the webhook.
failures	Every failure, as Request path: test name — error, or Request path: error for a request that couldn’t be sent.

Nothing is sent for passing runs. The webhook is only called when the URL includes a host.

Failure messages can contain response data

Test error messages can quote values from responses. Send failure webhooks only to channels where the people who can read them are allowed to see that data.

Monitor around the clock with cloakctl

A monitor in the app needs the app open. To run the same check on a schedule without it, call cloakctl collection run from cron or a CI scheduler. It exits with 1 when any test fails, so the scheduler can alert you.

crontab -e

# Every 15 minutes, run the Petstore collection against Staging and keep a JUnit report.
*/15 * * * * /usr/local/bin/cloakctl collection run "Petstore" -e Staging -r junit --reporter-junit-export "$HOME/petstore-monitor.xml"

Use the full path to cloakctl in cron (which cloakctl prints it). See Collection runner for every flag and Headless and CI for CI setups.

Receive webhooks

The webhook receiver gives you a local URL to point a service’s webhooks at while you develop.

1. Click Webhooks in the left rail.

2. Set the Port (default 9999), the status code to Respond with (default 200) and the response body (default {"received":true}).

3. Optionally enter a URL in Forward to (optional), such as your dev server’s webhook endpoint.

4. Click Start Listening.

   The receiver’s URL appears, for example http://localhost:9999. Any path and any method on that port is accepted.

5. Send a delivery to it. For a quick test:

   Terminal

   curl -X POST http://localhost:9999/hooks/orders -H "Content-Type: application/json" -d '{"event":"order.paid","id":"ord_123"}'

6. Click Stop when you’re done.

1234

The webhook receiver before it starts listening.

1. Port to listen on
2. Status code and body every delivery gets back
3. Optional URL to forward each delivery to
4. Start Listening

×

Webhook receiver settings

Setting	Default	What it does
Port	9999	The port to listen on. Can’t be changed while listening. If the port is taken, Cloak Proxy shows Couldn’t listen on port with the reason.
Respond with (status)	200	The status code every delivery gets. Use a 500 to test how the sender retries.
Response body	{"received":true}	The body every delivery gets, sent as application/json.
Forward to (optional)	Empty	A URL that each delivery is sent on to, as it arrives.

Changes to the status code and the forward URL apply right away. A new response body applies the next time you start listening.

Inspect a delivery

Deliveries appear in the list as they arrive, newest first. Each row shows the method and path, the time and the body size, and, when forwarding is on, the status your server returned (→ 200) or forward failed.

Select a delivery to see every request header and the body, with the same viewers the inspector uses for JSON, form data and other formats. The receiver keeps the latest 500 deliveries while the app is open; they aren’t saved to disk.

Forward and replay deliveries

Action	What it does
Forward to	Sends every new delivery to this URL as it arrives, with the same method, headers and body. Host, Content-Length and Connection are left out. The URL is used exactly as typed; the delivery’s path isn’t added to it.
Replay	With a delivery selected, type a URL in Replay to URL and click Replay to send that delivery again. The result shows as Replayed: and the status, or Replay failed: and the reason.
Open as Request	Opens the delivery as a new, unsaved request in the API client, with its method, headers and body. The URL is the Replay to URL, or http://localhost:3000 plus the delivery’s path when that field is empty. Edit it and send it as often as you like.

Forwarded and replayed requests go straight to the target, not through the proxy.

Tip

Replay is useful when a handler fails: fix the code, then replay the same delivery instead of triggering the event again in the other service.

Receive webhooks from the internet

The receiver listens on 127.0.0.1, so only this Mac can reach it. To receive deliveries from a service on the internet, expose the port with a tunnel such as cloudflared or ngrok, then give the service the tunnel’s public URL.

Terminal

cloudflared tunnel --url http://localhost:9999

A tunnel makes the receiver public

While a tunnel runs, anyone with its URL can send requests to the receiver, and through Forward to, to your dev server. Deliveries often carry customer data and signing secrets. Use the tunnel only while you’re testing, verify webhook signatures in your own handler, and stop both the tunnel and the receiver when you’re done.

Trigger a flow from a webhook

A flow can run each time a delivery arrives at a path you choose, for example /flows/nightly-sync. Turn on Run when a webhook arrives at in the flow’s Automation settings and start the receiver. The delivery is available in the flow as the trigger variable. See Automate a flow.

Related

Collection runnerWhat a monitor runs, and how to run it yourself.

FlowsChain requests and run them on a schedule or webhook.

Debug webhooks and callbacksA step-by-step guide.

Headless and CIRun collections from cron and CI.