# Triggering tests with webhooks

Run a test from anywhere, including CI pipelines, deploy scripts, and dashboards, by hitting its trigger URL.

Webhooks are how you run a Testsnag test from somewhere outside Testsnag. CI pipelines, custom dashboards, deploy scripts, and other monitoring tools can all hit a webhook URL to fire a run on demand. They are the right choice whenever a Testsnag test should happen in response to an event, and a schedule alone is not precise enough to catch the moment that matters.

![The Webhooks tab showing an outgoing endpoint and the inbound trigger URL section.](https://testsnag.com/images/docs/notifications/outbound-webhooks-1-endpoint.r1.jpg)

Marked on the screenshot:
- The inbound trigger URL. POST to it from CI to start a run.
- Anyone with this URL can fire the test, so treat it as a secret.

## Trigger URLs

Each test and each suite has its own trigger URL, generated on its Settings page. Sending a POST request to that URL starts a run immediately and returns a JSON acknowledgement with the run reference, which you can use to look the run up later. There is no body required for the simplest case, since a bare POST is enough to fire a run with default behaviour.

## Sending a payload

You can also include an optional JSON body of up to 64 KB in the request, and Testsnag records it as part of the run's metadata. That is useful for tagging runs with context such as the deploy SHA, the environment, the branch name, the build number, or the user who triggered it. Anything you record can later be viewed on the run detail page and used in debugging when a run fails. The bigger the deployment, the more you will appreciate having the right context attached to the right run.

## Choosing an environment

To run in an [environment](https://testsnag.com/docs/building-blocks/environments.md), add it to the query string of the trigger URL. Use the environment name, or all for every environment enabled for the test.

```text
POST <trigger URL>?environment=Staging
POST <trigger URL>?environments=all
```

- Only the query string selects an environment. An environment field in the JSON body is stored as metadata and does not change where the test runs.
- An unknown environment, or one not enabled for the test, returns a 422 and starts nothing.
- With several environments, the response includes a runs list with one entry per environment.
- A test trigger URL with no environment parameter runs with no environment. A suite trigger URL with no parameter uses the suite's own environment setting.

## Keeping trigger URLs safe

Webhook URLs are sensitive. Anyone who has the URL can fire the test, and the test will run with the same identity and quota as a manual run. Treat the URL like an API token, which means keeping it out of public repositories, storing it in your CI's secrets store, and rotating it if you have any reason to think it leaked. Regenerating the URL in the Settings page is one click, and the previous URL stops working immediately so accidental exposure is easy to recover from.

## Wiring it into CI

The Settings page also includes a copy-paste cURL example, which is enough to wire most things up in a single line of CI configuration. For more elaborate setups, including passing build metadata, gating on the response, or retrying on failure, any HTTP client will work because the endpoint is a plain JSON API with no special protocol of its own.