> For the complete documentation index, see [llms.txt](https://docs.does.qa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.does.qa/platform/integrations/universal-webhook.md).

# Universal Webhook

The Universal Webhook is how almost any external system can start a DoesQA Run. Your pipeline, automation platform, or custom script sends an HTTP request. DoesQA selects Flows, starts the Run, and keeps going.

With this you can create an integration with any other service, or a script you own. One URL and key unlock Runs from GitHub, Bitbucket, Azure DevOps, Make, Zapier, n8n, and anything else that can send HTTP.

{% hint style="info" %}
This is the **inbound** hook that starts Runs. It is not the outbound notification webhook that posts results when a Run finishes. For outbound results, see [Notifications](/configuration/notifications.md).
{% endhint %}

## Why use it

* One URL and key work across CI tools and no-code platforms.
* You choose Flows with IDs, a [Run Recipe](/configuration/run-recipes.md), or tags.
* You can preview the selection with GET before you wire a pipeline.
* You can return immediately, or wait until the Run finishes.

Create and manage keys under **Settings → CI/CD**. Field-by-field detail for that screen lives on [CI / CD](/configuration/ci-cd.md).

## Before you call the hook

{% stepper %}
{% step %}

## Create a CI/CD key

In DoesQA, open **Settings → CI/CD**, create an **Active** key, and store the secret in your other system. DoesQA shows the secret once. See [CI / CD](/configuration/ci-cd.md).
{% endstep %}

{% step %}

## Copy your Account ID

Open **Settings** (Account Settings) and copy the **Account ID**. It is part of the hook URL.
{% endstep %}

{% step %}

## Decide how to select Flows

Pick one selection style per request. If more than one is present, DoesQA uses the first match in this order:

1. Flow IDs (`ids`)
2. A [Run Recipe](/configuration/run-recipes.md) (`recipe`)
3. Tags (`withAll` / `withoutAny`)
4. All Flows in the account

**Include tags** (`withAll`) mean the Flow must have every listed tag. **Exclude tags** (`withoutAny`) remove a Flow if it has any listed tag.
{% endstep %}
{% endstepper %}

## Preview which Flows would run

Send a **GET**. Nothing starts.

```
GET https://app.does.qa/api/hook/ACCOUNT_ID?key=YOUR_KEY&withAll=smoke
```

Check the response count against the Flows you expect. Fix tags, recipe, or IDs before you add the call to CI or an automation.

## Start a Run

Send a **POST**:

```
POST https://app.does.qa/api/hook/ACCOUNT_ID?key=YOUR_KEY&withAll=smoke&label=Build%201234
```

By default the hook accepts the request and returns quickly while the Run continues. To wait until the Run finishes before your job continues, add `mode=wait`.

### Request options

| Parameter     | Required | What it does                                                                                  |
| ------------- | -------- | --------------------------------------------------------------------------------------------- |
| `key`         | Yes      | Your CI/CD webhook key. You can also send it as the `x-api-key` header.                       |
| `label`       | No       | Label shown on the Run, such as a build number.                                               |
| `ids`         | No       | Comma-separated Flow IDs.                                                                     |
| `recipe`      | No       | Run Recipe ID.                                                                                |
| `withAll`     | No       | Comma-separated include tags. The Flow must have all of them.                                 |
| `withoutAny`  | No       | Comma-separated exclude tags. The Flow must have none of them.                                |
| `values`      | No       | URL-encoded JSON object of Value overrides.                                                   |
| `testsTagged` | No       | Only Test Cases that have this tag.                                                           |
| `mode`        | No       | `fast` (default) returns as soon as the Run is accepted. `wait` holds until the Run finishes. |

Authenticate with the query `key`, or with header `x-api-key: YOUR_KEY`.

Optional **Value** overrides replace matching items from the [Value Store](/values/value-store.md) for that Run.

### Example with Value overrides

```
POST https://app.does.qa/api/hook/ACCOUNT_ID?key=YOUR_KEY&withAll=staging&label=PR-88&values=%7B%22BASE_URL%22%3A%22https%3A%2F%2Fstaging.example.com%22%7D
```

Decoded, `values` is:

```json
{
  "BASE_URL": "https://staging.example.com"
}
```

### Minimal curl example

```bash
curl -X POST \
  "https://app.does.qa/api/hook/ACCOUNT_ID?key=YOUR_KEY&withAll=smoke&label=manual-check"
```

## Ready-made examples

| Tool         | Page                                                   |
| ------------ | ------------------------------------------------------ |
| GitHub       | [GitHub](/platform/integrations/github.md)             |
| GitLab       | [GitLab](/platform/integrations/gitlab.md)             |
| Bitbucket    | [Bitbucket](/platform/integrations/bitbucket.md)       |
| Azure DevOps | [Azure DevOps](/platform/integrations/azure-devops.md) |
| Make         | [Make](/platform/integrations/make.md)                 |
| Zapier       | [Zapier](/platform/integrations/zapier.md)             |
| n8n          | [n8n](/platform/integrations/n8n.md)                   |

Prefer a ready-made flow when one exists. Otherwise paste the [curl example](#minimal-curl-example) into the service or script you already use, and you are connected.

## After the Run starts

To post results to Slack, Teams, email, or an outbound webhook, create a notification rule and include the **CI/CD Webhook** run type. See [Notifications](/configuration/notifications.md).

## Related

* [Integrations](/platform/integrations.md)
* [CI / CD](/configuration/ci-cd.md)
* [Notifications](/configuration/notifications.md)
* [Run Recipes](/configuration/run-recipes.md)
* [Build smoke and regression coverage](/better-coverage/build-smoke-and-regression-coverage.md)