Skip to content

API Access (CI/CD Integration)

Trigger a Monitor run from your CI pipeline with an API key, and get results pushed straight to Slack or Microsoft Teams (or a generic JSON endpoint) with webhooks — instead of waiting for the scheduled run or only getting an email.

Requires a Business (or Enterprise) plan. Solo, Team, and trial workspaces don't have access to API keys or webhooks at all — see Subscription and billing.

Manage both from Workspace settings → API access.

Triggering a monitor from CI

  1. Open API access and create an API key (just needs a name, e.g. "GitHub Actions"). The raw key is shown exactly once — copy it now and store it as a CI secret. If you lose it, revoke it and create a new one; there's no way to view it again.
  2. On the Monitors list for the project you want to trigger, click Copy CI command next to any monitor. It copies a ready-to-run command like:
curl -X POST -H "x-api-key: YOUR_API_KEY" https://<your-app-domain>/api/monitors/<monitor-id>/ci-trigger
  1. Paste your real API key in place of YOUR_API_KEY (e.g. as a CI secret reference) and add this as a step in your pipeline — after a deploy finishes, for example.

Prefer a ready-made pipeline step over a raw curl command? Click CI snippets next to Copy CI command for a copy-pasteable GitHub Actions, GitLab CI, or Azure DevOps step using the same API key — no new endpoint, just a different way to paste the same call.

Calling it queues an immediate run of that monitor with its existing configuration (scope, baseline, sensitivity) — the same as clicking "Run now" in the dashboard. The call returns right away; it doesn't wait for the screenshots/comparison to finish. Check the dashboard, or a configured webhook, for the result.

A key works for any monitor in its workspace — you don't need a separate key per monitor or per project. It's limited to 60 trigger calls per hour to keep one misconfigured pipeline from hammering your workspace.

If you no longer need a key (a pipeline is decommissioned, a key leaked), Revoke it — it stops working immediately. Revoked keys stay listed (so you can see they existed) but can't be un-revoked; create a new one instead.

Sending results to Slack or Microsoft Teams

A webhook posts a message every time a monitored change or failure happens — in real time, independent of your monitors' own email settings (so you can use Slack/Teams as your only alert channel and turn monitor emails off, or run both side by side).

Setting up Slack

  1. In Slack, create an Incoming Webhook for the channel you want alerts in (Slack → Apps → search "Incoming Webhooks" → Add to Slack → choose a channel). Copy the webhook URL it gives you.
  2. In VisualRunner's API access page, create a webhook: paste that URL, choose provider Slack, and pick which events should post (visual change detected, run failed, run failing repeatedly).
  3. Click Send test to confirm it posts to the right channel before relying on it.

Setting up Microsoft Teams

  1. In Teams, add a Workflows webhook to the channel (⋯ next to the channel → Workflows → "Post to a channel when a webhook request is received" → follow the prompts). Copy the URL it gives you. This is the current, supported way to receive incoming webhooks in Teams — the older "Connectors" webhook type is being retired by Microsoft, so if you're offered that option instead, use Workflows.
  2. In VisualRunner's API access page, create a webhook: paste that URL, choose provider Microsoft Teams, and pick which events should post.
  3. Click Send test to confirm the card renders properly in your channel.

Generic (your own endpoint)

Choose provider Generic to receive a plain JSON body instead — useful if you're piping alerts into your own system rather than Slack/Teams. Every request includes an X-VisualRunner-Signature header (an HMAC-SHA256 of the request body, signed with the secret shown when you created the webhook) so your endpoint can verify the request genuinely came from VisualRunner and wasn't forged. Like the API key, the signing secret is shown exactly once, at creation — save it somewhere safe.

Managing webhooks

  • Disable/Enable pauses or resumes delivery without losing the configuration (URL, secret, and selected events are all kept).
  • Delete removes it permanently — unlike revoking an API key, a deleted webhook is gone for good, not kept around for reference.
  • A webhook only fires for the events you selected — untick "Run failed" if you only want to hear about visual changes, for example.
  • If a delivery fails (your endpoint was briefly down, a bad response, etc.), VisualRunner retries automatically a few times before giving up — you don't need to manually resend anything.

Want a change or failure to automatically create a Jira issue, or to route events conditionally (only page on-call for production escalations, say)? See Jira & Automation Rules — both build on top of the API keys/webhooks described here.

Plan limits

Plan API keys Webhooks Jira project mappings Automation rules
Solo / Team Not available Not available Not available Not available
Trial Not available Not available Not available Not available
Business 5 3 3 10
Enterprise 5 3 5 25

See also