> ## 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.

# webhooks/deploy_success

> Notify QA Wolf of a successful deployment to trigger a test run, including request format, headers, body fields, and example responses.

`POST https://app.qawolf.com/api/webhooks/deploy_success`

<Tip>
  If your build server supports `node`, use [`@qawolf/ci-sdk`](/libraries/ci-sdk/api-reference) instead of calling this endpoint directly. This gives you type safety and clearer errors and output.
</Tip>

## Request

```bash theme={null}
curl -X POST https://app.qawolf.com/api/webhooks/deploy_success \
  -H "Authorization: Bearer $QAWOLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "sha": "de12adda500f2bc5a29dbd89f4fb1b0e1a31de81",
    "deployment_type": "staging",
    "deployment_url": "https://staging.example.com",
    "hosting_service": "GitHub",
    "workspaceId": "ckz2y0o7j01914cgtra6lk4wn"
  }'
```

## Request headers

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer <your-api-key>` |
| `Content-Type`  | `application/json`      |

## Request body

All fields are optional.

### Commonly used

| Field             | Type   | Description                                                                                         |
| ----------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `branch`          | string | Git branch name. Used to display in the UI and match pull requests on any linked repo.              |
| `sha`             | string | Git commit SHA. Used to create GitHub commit checks and display a link to the commit in the run UI. |
| `deployment_type` | string | Required if the target trigger is configured to match a deployment type.                            |
| `deployment_url`  | string | Overrides the environment URL. Available in tests as `process.env.URL`.                             |

### Advanced

| Field                   | Type    | Description                                                                                                                                                                                                                                                                                      |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hosting_service`       | string  | `"GitHub"` or `"GitLab"`. Defaults to `"GitHub"`.                                                                                                                                                                                                                                                |
| `commit_url`            | string  | Pass with `sha` if no hosting service repo is configured. Makes the commit ID a clickable link in the QA Wolf UI.                                                                                                                                                                                |
| `variables`             | object  | Key/value pairs that override environment variables for every run triggered by this notification.                                                                                                                                                                                                |
| `deduplication_key`     | string  | Custom key controlling run cancellation behavior. By default, new runs cancel ongoing runs with the same branch/environment combination.                                                                                                                                                         |
| `ephemeral_environment` | boolean | Pass with `deployment_url` if the deployment is not associated with a code-hosting integration.                                                                                                                                                                                                  |
| `workspaceId`           | string  | Workspace to create runs in. Ignored by a workspace API key, which already implies its workspace. With an organization or user API key, omitting it uses your organization's first-created workspace. See [which workspace a request acts on](/rest-overview#which-workspace-a-request-acts-on). |

## Response

```json theme={null}
{
  "results": [
    {
      "created_suite_id": "cl1f6i0in15676w115vt43vw2",
      "outcome": "created",
      "trigger_id": "ckzoog9wy01720xyrvl8ah7gu"
    }
  ]
}
```

`results` is an array of matched triggers. Each entry carries an `outcome` of `created`, `skipped`, or `failed`, alongside `created_suite_id` if QA Wolf created a run, `duplicate_suite_id` if a run for this deployment already exists, or `failure_code` and `failure_message` if QA Wolf could not create the run. Branch on `failure_code`, such as `billing-prevented` or `environment-not-ready`, and display `failure_message`. Treat `failure_code` as an open set, since QA Wolf adds new codes over time.

<Warning>
  A failed entry also carries `failure_reason`, which is deprecated. It holds an internal diagnostic whose values change without notice, so do not branch on it.
</Warning>

`warning` is present when the request needed a workspace and did not name one, in which case it reports the workspace QA Wolf used. It never changes the outcome. `@qawolf/ci-sdk` prints it for you.

```json theme={null}
{
  "results": [
    {
      "created_suite_id": "cl1f6i0in15676w115vt43vw2",
      "outcome": "created",
      "trigger_id": "ckzoog9wy01720xyrvl8ah7gu"
    }
  ],
  "warning": "No workspaceId was sent, so this request used your first-created workspace: Acme (ckz2y0o7j01914cgtra6lk4wn). Send workspaceId to choose explicitly."
}
```

On the first delivery of a deployment, a matched trigger returns `created_suite_id` even when the deployment duplicates one QA Wolf is already handling. Deduplication is settled after this response is sent, so the synchronous response does not report it. To find out whether a duplicate superseded your run, poll [CI greenlight](/v0-ci-greenlight) and compare `relevantRunId` with `rootRunId` (see [Superseding logic](/v0-ci-greenlight#superseding-logic)).

<Note>
  You see `duplicate_suite_id` only when retrying `deploy_success` for the same `sha` after deduplication has already settled. On the first delivery, QA Wolf never reports a matched trigger as a duplicate.
</Note>

## Response codes

| Code  | Description                                                               |
| ----- | ------------------------------------------------------------------------- |
| `200` | Request accepted. Inspect the response body to confirm a run was created. |
| `401` | Missing or invalid API key.                                               |
| `403` | Forbidden. Usually indicates a disabled workspace.                        |
| `404` | Run not found.                                                            |
| `405` | Method not allowed. Use `POST`.                                           |
| `500` | Internal server error. Contact support if the issue persists.             |

<Note>
  A 200 response does not guarantee a run was created. Inspect the response body to confirm.
</Note>

## Related

* [`@qawolf/ci-sdk`](/libraries/ci-sdk/api-reference)
* [CI greenlight](/v0-ci-greenlight)