> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qawolf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Report a deploy to QA Wolf straight from your pipeline, for a CI system QA Wolf's code host integrations do not cover.

When your pipeline cannot create a GitHub or GitLab deployment, it can tell QA Wolf about the deploy itself. The `deployment.reportStatus` route takes the same information a deployment event carries, and a [trigger](/triggers/overview) evaluates it the same way.

Pick this path when your code host is not GitHub or GitLab, when the deploying repository is not connected, or when the deploy happens somewhere your code host never sees.

## Requirements

* An organization or user API key, created under **Workspace Settings → API Keys**. A workspace key cannot call this route.
* The ability to make an authenticated HTTPS request from your pipeline.

## What a report carries

| Field                  | Description                                                                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workspaceId`          | The workspace to report the deployment into.                                                                                                                             |
| `providerDeploymentId` | Your identifier for the deployment. Reports carrying the same one update a single deployment.                                                                            |
| `status`               | `pending`, `success`, `failure` or `inactive`.                                                                                                                           |
| `environment`          | Either `{ id }` for an existing environment, or `{ name }`, which resolves by alias or name and creates an environment when nothing matches.                             |
| `deployTarget`         | The URL the deployment serves.                                                                                                                                           |
| `environmentVariables` | Overrides for the runs this deployment requests, as a flat map of string to string. A report that sends them replaces the stored values; one that omits them keeps them. |
| `metadata`             | Details about the deployed revision, such as the commit.                                                                                                                 |

## The request

Example:

```bash theme={null}
curl -X POST "https://app.qawolf.com/api/trpc/public.deployment.reportStatus" \
  -H "Authorization: Bearer $QAWOLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"json\": {
      \"workspaceId\": \"$QAWOLF_WORKSPACE_ID\",
      \"providerDeploymentId\": \"$DEPLOY_ID\",
      \"status\": \"success\",
      \"environment\": { \"name\": \"staging\" },
      \"deployTarget\": \"https://staging.example.com\",
      \"metadata\": { \"commitSha\": \"$GIT_COMMIT_SHA\", \"ref\": \"$GIT_BRANCH\" }
    }
  }"
```

The input goes inside a `json` wrapper, and the reply carries the deployment under `result.data.json`. Replace `$DEPLOY_ID` with whatever your pipeline calls this deploy — a build number or a pipeline id — and `$QAWOLF_WORKSPACE_ID` with the id from **Workspace Settings → API Keys**.

### Metadata

`metadata` describes the revision you deployed. Every field is optional, and each one QA Wolf receives makes the deployment easier to recognize and to link back to your code.

| Field               | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| `commitSha`         | The commit sha of the deployed revision.                                  |
| `ref`               | The branch or ref that was deployed.                                      |
| `repository`        | The `owner/name` of the repository, such as `acme/web`.                   |
| `pullRequestNumber` | The pull request the deployment belongs to. Requires `repository`.        |
| `commitMessage`     | The deployed commit's message. The deployments list shows its first line. |
| `commitAuthorName`  | The display name of the commit's author.                                  |

Sending `repository` and `pullRequestNumber` is what lets a preview deploy resolve to its pull request, which [generative flow selection](/triggers/overview#generative-flow-selection) needs.

## When a report starts a run

* A deployment's first `success` report evaluates triggers, and it is the only report that does. A trigger added or resumed afterwards does not make that deployment evaluate again — report the deploy under a new `providerDeploymentId` to evaluate it against the triggers as they stand.
* The response carries the deployment only, never the resulting runs.

A deployment stays bound to the environment resolved on its first report, so later reports may omit the selector. Report a promotion as a new deployment under a new `providerDeploymentId`.

The environment you name decides where the runs happen, and the same matching rules apply as for a deployment event. See [the environment name is the contract](/triggers/report-deployments#the-environment-name-is-the-contract) and, for previews, [isolate previews per pull request](/triggers/report-deployments#isolate-previews-per-pull-request).

## Create a trigger

Reporting a deploy starts nothing on its own. Create a deployment trigger whose conditions match the deployments you now report, and name the flows it runs. See [Set up a trigger](/triggers/set-up-a-trigger).