deploy-success.mdx

title	webhooks/deploy_success
description	Notify QA Wolf of a successful deployment to trigger a test run, including request format, headers, body fields, and example responses.
sidebarTitle	Notify a deploy (legacy)

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

This endpoint feeds legacy triggers. A workspace that has migrated reports deploys through deployment events or deployment.reportStatus, which this endpoint does not reach.

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.

Request

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.

Response

{
  "deployment_id": "cl9k2p0aa00031vzq4t8xh3mn",
  "environment": "Staging",
  "results": [
    {
      "created_suite_id": "cl1f6i0in15676w115vt43vw2",
      "environment_id": "ckz2y0o7j01914cgtra6lk4wn",
      "outcome": "created",
      "trigger_id": "ckzoog9wy01720xyrvl8ah7gu"
    }
  ]
}

deployment_id and environment identify the deployment QA Wolf recorded. skipped_deployment is present instead of triggering runs when QA Wolf skipped the deployment, carrying a reason and a message.

results is an array of matched triggers. Every entry carries environment_id, and a skipped entry carries skip_reason. 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.

Success bodies use snake_case and error bodies use camelCase: a 402, 429 or 503 returns failureCode and failureMessage, not failure_code and failure_message. Handle both spellings.

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

{
  "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 and compare relevantRunId with rootRunId (see Superseding logic).

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.

Response codes

Code	Description
200	Request accepted. Inspect the response body to confirm a run was created.
400	Invalid request body. The response carries an error describing the problem.
402	Billing prevented the run. Returns failureCode: "BILLING_PREVENTED".
429	Too many requests for this workspace. Returns failureCode: "RATE_LIMITED" and a Retry-After header giving the seconds to wait.
503	QA Wolf is briefly unable to process the request. Returns failureCode: "TRANSACTION_TIMEOUT". Retry in a few moments.

Plus the common response codes.

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

Related

• @qawolf/ci-sdk
• CI greenlight