> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tester.army/run/llms.txt.
> For full documentation content, see https://docs.tester.army/run/llms-full.txt.

# Group Webhooks

Group webhooks let you run every test in a group with one HTTP call. Works with any CI/CD pipeline, deployment tool, or custom automation.

## Setup

1. Open your project → **Tests** tab.
2. Expand a group and click the **trigger badge** (lightning icon).
3. Toggle **Enable webhook** on.
4. Click **Save**.
5. Copy the URL - the secret is shown once.

## Trigger

```bash
curl -X POST https://tester.army/api/v1/groups/webhook/{id}/{secret}
```

All tests in the group are queued against the project's configured URL.

### Optional body

You can pass JSON to attach commit metadata:

```bash
curl -X POST https://tester.army/api/v1/groups/webhook/{id}/{secret} \
  -H "Content-Type: application/json" \
  -d '{
    "commitSha": "abc123"
  }'
```

### Mobile app override

You can override the iOS app build used by mobile tests in the group.

**By bundle ID** — resolves to the latest uploaded app matching that bundle identifier:

```bash
curl -X POST https://tester.army/api/v1/groups/webhook/{id}/{secret} \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": {
      "bundleId": "com.example.app",
      "buildId": "44"
    }
  }'
```

**By app ID** — targets a specific uploaded build by its UUID (returned from the upload API):

```bash
curl -X POST https://tester.army/api/v1/groups/webhook/{id}/{secret} \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": {
      "appId": "<YOUR APP UPLOAD ID>"
    }
  }'
```

Use `appId` when multiple builds share the same bundle ID and you need to pin a specific upload.

**By remote artifact** — provide an HTTPS URL and filename for remote build artifacts:

```bash
curl -X POST https://tester.army/api/v1/groups/webhook/{id}/{secret} \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": {
      "artifactUrl": "https://example.com/builds/MyApp.app.zip",
      "artifactFilename": "MyApp.app.zip",
      "buildId": "eas-982"
    }
  }'
```

Only one of `bundleId`, `appId`, or `artifactUrl` can be provided per request.

### Response

```json
{
  "received": true,
  "status": "queued",
  "runIds": ["uuid-1", "uuid-2"],
  "count": 2
}
```

When the batch contains iOS tests, the response includes `metadata.mobile`:

```json
{
  "received": true,
  "status": "queued",
  "runIds": ["uuid-1", "uuid-2"],
  "count": 2,
  "metadata": {
    "mobile": {
      "resolvedAppId": "11111111-1111-1111-8111-111111111111",
      "source": "app_id",
      "buildId": "44",
      "temporary": false
    }
  }
}
```

* `source: "test_default"` means each iOS test used its saved app selection.
* `source: "app_id"` means the webhook used an already uploaded project app, selected by `bundleId` or `appId`.
* `source: "artifact_url"` means TesterArmy imported the artifact for this batch.

Artifact-imported apps are temporary. They are removed automatically after every run in the webhook batch reaches a terminal state.

## Failure notifications

When a webhook-triggered batch completes and any test fails, TesterArmy sends the failure summary by email only when the batch does **not** include GitHub commit context. Batches triggered with `commitSha` report back through GitHub instead of email.

## Limits

* **1 webhook per group.** Delete and recreate to regenerate the secret.
* Subject to your team's usage limits - returns `429` if exceeded.
* Webhook must be **active** (saved) to accept requests. Inactive webhooks return `403`.