qawolf · John Gluck (JohnGluck) · May 28, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/docs.json b/docs.json
@@ -299,9 +299,29 @@
         ]
       },
       {
-        "tab": "Libraries",
+        "tab": "References",
         "icon": "braces",
         "pages": [
+          {
+            "group": "@qawolf/emails",
+            "icon": "mail",
+            "pages": [
+              {
+                "group": "API Reference",
+                "pages": [
+                  "qawolf/libraries/emails/api-reference/index",
+                  "qawolf/libraries/emails/api-reference/mail",
+                  "qawolf/libraries/emails/api-reference/client"
+                ]
+              },
+              {
+                "group": "Troubleshooting",
+                "pages": [
+                  "qawolf/libraries/emails/troubleshooting"
+                ]
+              }
+            ]
+          },
           {
             "group": "@qawolf/flows",
             "icon": "route",
@@ -350,23 +370,14 @@
             ]
           },
           {
-            "group": "@qawolf/emails",
-            "icon": "mail",
+            "group": "REST",
+            "icon": "code",
             "pages": [
-              {
-                "group": "API Reference",
-                "pages": [
-                  "qawolf/libraries/emails/api-reference/index",
-                  "qawolf/libraries/emails/api-reference/mail",
-                  "qawolf/libraries/emails/api-reference/client"
-                ]
-              },
-              {
-                "group": "Troubleshooting",
-                "pages": [
-                  "qawolf/libraries/emails/troubleshooting"
-                ]
-              }
+              "qawolf/rest-overview",
+              "qawolf/deploy-success",
+              "qawolf/environment_terminated",
+              "qawolf/v0-ci-greenlight",
+              "qawolf/run-inputs-executables-signed-urls"
             ]
           }
         ]
@@ -386,7 +397,9 @@
                 "pages": [
                   "qawolf/GitHub-GitHub-Actions-2a15b2a994fb800699f6dc99584915d0",
                   "qawolf/GitLab-2a15b2a994fb805d9d14ff27726065ae",
-                  "qawolf/circle-ci"
+                  "qawolf/circle-ci",
+                  "qawolf/other-ci-node",
+                  "qawolf/other-ci-webhook"
                 ]
               },
               {

diff --git a/qawolf/GitLab-2a15b2a994fb805d9d14ff27726065ae.mdx b/qawolf/GitLab-2a15b2a994fb805d9d14ff27726065ae.mdx
@@ -123,4 +123,20 @@ This job tells QA Wolf that a new deployment is ready for testing.
   <Step>
     Open QA Wolf and confirm a new run appears under the expected environment.
   </Step>
-</Steps>
+</Steps>
+
+## Verify the integration
+
+<Steps>
+  <Step>
+    Push a new commit to your main branch and wait for your deployment to complete.
+  </Step>
+  <Step>
+    Open QA Wolf and confirm a new run appears under the expected environment.
+  </Step>
+</Steps>
+
+## Related
+
+- [webhooks/deploy\_success](/qawolf/deploy-success)
+- [REST API](/qawolf/rest-overview)
diff --git a/qawolf/Mobile-build-with-the-QA-Wolf-SDK-2db5b2a994fb80cdbd1ec31513f2cc15.mdx b/qawolf/Mobile-build-with-the-QA-Wolf-SDK-2db5b2a994fb80cdbd1ec31513f2cc15.mdx
@@ -1,19 +1,23 @@
 ---
-title: "How to integrate a mobile build with the QA Wolf SDK"
+title: "How to integrate mobile builds with our SDK"
 description: "Upload mobile build artifacts and trigger test runs from any CI system using the QA Wolf CI SDK."
-sidebarTitle: "QA Wolf SDK"
+sidebarTitle: "Other CI (Node.js)"
 ---
 
-## When to use the QA Wolf SDK
+Use this guide if your CI system supports Node.js but is not GitHub Actions or Fastlane.
 
-This guide is for teams that do not use Fastlane or want a single, flexible way to upload mobile builds and trigger test runs from any CI system. Use the QA Wolf CI SDK if your mobile builds are produced directly in CI scripts; you want the same integration approach for mobile and web testing; you are not using GitHub Actions or prefer not to rely on prebuilt actions; or you need fine-grained control over when artifacts are uploaded and runs are triggered. This guide assumes only that your CI system can run Node.js.
+<Tip>
+  If your CI system does not support Node.js, contact your QA Wolf representative for guidance.
+</Tip>
 
-## Before you begin
+<Check>
+  Make sure you have:
 
-1. Make sure you have a CI pipeline that produces a mobile build artifact (APK, AAB, or IPA).
-2. Node.js 18 or later is available in your CI environment.
-3. A QA Wolf API key is stored as a CI secret (**QAWOLF\_API\_KEY**).
-4. Artifact naming conventions are defined for your environments. See [Artifact naming conventions](#artifact-naming-conventions) below.
+  - A CI pipeline that produces a mobile build artifact (APK, AAB, or IPA)
+  - Node.js 18 or later available in your CI environment
+  - Admin access to your CI system's secret or environment variable storage
+  - A QA Wolf API key
+</Check>
 
 Before mobile test runs can execute, QA Wolf must enable mobile triggers for your workspace. QA Wolf will handle this and may ask you for:
 
@@ -24,25 +28,6 @@
 
 Until this step is complete, CI jobs can upload artifacts and send deployment notifications, but mobile test runs will not start automatically.
 
-## How the QA Wolf SDK works
-
-The CI SDK performs two main tasks:
-
-<Steps>
-  <Step>
-    Upload a mobile build artifact to QA Wolf.
-  </Step>
-  <Step>
-    Notify QA Wolf of a deployment event to trigger a test run.
-  </Step>
-</Steps>
-
-<Tip>
-  You can upload builds without triggering runs, which is useful during initial setup or validation.
-</Tip>
-
-You provide the [artifact basename](#artifact-naming-conventions) when uploading. QA Wolf applies the file extension automatically based on the uploaded file.
-
 ## Install the CI SDK
 
 Install the SDK in your CI job:
@@ -51,21 +36,17 @@
 npm install @qawolf/ci-sdk
 ```
 
-### Find the QAWOLF\_API\_KEY
+## Find the QAWOLF\_API\_KEY
 
 <Steps>
   <Step>
-    Open the `Workspace name` dropdown in QA Wolf and click **Workspace Settings**.
+    Open the **Workspace name** dropdown in QA Wolf and click **Workspace Settings**.
   </Step>
   <Step>
     Choose **Integrations**.
   </Step>
   <Step>
     Generate your **QAWOLF\_API\_KEY** by clicking the <Icon icon="clipboard" /> icon to the right of **API Key** under **API Access**.
-
-    <Frame>
-      ![](/images/integrating-with-CI-CD/image-16.png)
-    </Frame>
   </Step>
 </Steps>
 
@@ -77,9 +58,9 @@
 
 The artifact name is used to identify:
 
-- Which environment the build belongs to
-- Whether the build is tied to a pull request
-- Which build was used for a given test run
+- Which environment the build belongs to.
+- Whether the build is tied to a pull request.
+- Which build was used for a given test run.
 
 ### Static environments
 
@@ -97,7 +78,7 @@
 app-staging
 ```

 Use the same basename every time a build is generated for the same environment.

 ### PR (ephemeral) environments

@@ -118,7 +99,7 @@
 Including the organization, repository, and pull request number ensures each build can be traced back to the correct change and environment.

 <Tip>
  QA Wolf applies the file extension (.apk, .aab, or .ipa) automatically based on the uploaded artifact. You only need to provide the basename.
 </Tip>

 ## Upload a mobile build artifact
@@ -169,7 +150,7 @@
 
 const { generateSignedUrlForRunInputsExecutablesStorage, attemptNotifyDeploy } =
   makeQaWolfSdk({
-    apiKey: "qawolf_xxxxx",
+    apiKey: process.env.QAWOLF_API_KEY,
   });
 
 (async () => {
@@ -194,7 +175,6 @@
 
     const result = await attemptNotifyDeploy(deployConfig);
     if (result.outcome !== "success") {
-      // Fail the job.
       process.exit(1);
     }
     const runId = result.runId;
@@ -205,8 +185,6 @@
   const fileName = path.basename(filePath);
 
   const signedUrlResponse = await generateSignedUrlForRunInputsExecutablesStorage({
-    // for mobile apps, we prefer static filenames based on the environment name
-    // for example, use `app_staging.apk` for the Staging environment
     destinationFilePath: fileName,
   });
 
@@ -234,10 +212,6 @@
       return "";
     }
 
-    // for mobile apps, we request that you include this prefix path
-    // return `/home/wolf/run-inputs-executables/${signedUrlResponse.playgroundFileLocation}`;
-
-    // for other apps
     return signedUrlResponse.playgroundFileLocation;
   }
   return "";
@@ -283,6 +257,10 @@
 ## Troubleshooting and common issues

 - **If uploads succeed but no runs start:** Mobile triggers may not yet be enabled. Contact QA Wolf to complete platform configuration.
 - **If the artifact is not found during execution:** Verify that the artifact basename matches your naming conventions, and the returned path is used when triggering the run.
 - **If you see authentication errors:** Verify that **QAWOLF\_API\_KEY** is configured correctly in your CI environment.
-- **If you encounter Node.js errors:** Ensure Node.js 18 or later is available in the CI job.
+- **If you encounter Node.js errors:** Ensure Node.js 18 or later is available in the CI job.
+
+## Related
+
+- [`@qawolf/ci-sdk`](/qawolf/libraries/ci-sdk/api-reference)
diff --git a/qawolf/circle-ci.mdx b/qawolf/circle-ci.mdx
@@ -17,9 +17,7 @@ sidebarTitle: "CircleCI"
   - A QA Wolf API key
 </Check>
 
-## Set up your QAWOLF\_API\_KEY
-
-### Find the QAWOLF\_API\_KEY
+## Find the QAWOLF\_API\_KEY
 
 <Steps>
   <Step>
@@ -137,4 +135,6 @@ Place it after your deploy job in the workflow so it runs only once your environ
   </Step>
 </Steps>
 
-- [QA Wolf CI SDK](/qawolf/Integrate-with-the-QA-Wolf-SDK-2db5b2a994fb8043be61f06f025d9c63)
+## Related
+
+- [QA Wolf CI SDK](/qawolf/qawolf/other-ci-node)
diff --git a/qawolf/deploy-success.mdx b/qawolf/deploy-success.mdx
@@ -0,0 +1,91 @@
+---
+title: "webhooks/deploy_success"
+description: "Triggers a test run against a deployment."
+sidebarTitle: "webhooks/deploy_success"
+---
+
+`POST https://app.qawolf.com/api/webhooks/deploy_success`
+
+<Warning>
+  If your build server supports `node`, use [`@qawolf/ci-sdk`](/libraries/ci-sdk) instead of calling this endpoint directly.
+</Warning>
+
+## Request
+
+```bash
+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"
+  }'
+```
+
+## 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. |
+
+## Response
+
+```json
+{
+  "results": [
+    {
+      "created_suite_id": "cl1f6i0in15676w115vt43vw2",
+      "trigger_id": "ckzoog9wy01720xyrvl8ah7gu"
+    }
+  ]
+}
+```
+
+`results` is an array of matched triggers. Each entry contains either `created_suite_id` if a run was created, `duplicate_suite_id` if a run for this SHA already exists, or `failure_reason` if the run could not be created.
+
+## 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. |
+
+<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)
+- [CI greenlight](/rest/ci-greenlight)