webhooks/deploy_success

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

If your build server supports node, use @qawolf/ci-sdk 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

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

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

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

Flow conventions

@qawolf/flows

@qawolf/pom

@qawolf/testkit

@qawolf/emails

@qawolf/cli

Local execution

@qawolf/ci-sdk

REST

webhooks/deploy_success

Request

Request headers

Request body

Commonly used

Advanced

Response

Response codes

​Request

​Request headers

​Request body

​Commonly used

​Advanced

​Response

​Response codes

​Related

Request

Request headers

Request body

Commonly used

Advanced

Response

Response codes

Related