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 a run was created, duplicate_suite_id if a run for this deployment already exists, or failure_code and failure_message if the run could not be created. Branch on failure_code, such as billing-prevented or environment-not-ready, and display failure_message. Treat failure_code as an open set, since new codes are added 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 your run was superseded by a duplicate, 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, a matched trigger is never reported 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 team.
`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.

@qawolf/flows

@qawolf/pom

@qawolf/testkit

@qawolf/emails

@qawolf/ci-sdk

@qawolf/cli

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