> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run tests via webhook

> Trigger Qodex runs from CI, deploy scripts, or external systems using project API keys or schedule webhooks.

# Run tests via webhook

Webhooks let external systems start Qodex runs. Use them from CI pipelines, deploy scripts, release tools, or any service that can make an HTTP request.

There are two webhook styles: a flexible project trigger authenticated with an API key, and a preconfigured schedule URL with a baked-in secret.

## Project trigger

Use the project trigger when the caller needs to choose the environment, tags, or callback URL at request time.

```bash theme={null}
curl -X POST \
  https://agents.qodex.ai/api/projects/my-project-slug/webhooks/trigger \
  -H "Authorization: Bearer qk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "tags": ["smoke"],
    "callback_url": "https://ci.example.com/qodex-hook"
  }'
```

Project API keys start with `qk_`, are scoped to one project, and are stored only as hashes. The plaintext key is shown once when created.

## Request body

| Field          | Default   | Meaning                                         |
| -------------- | --------- | ----------------------------------------------- |
| `environment`  | `staging` | Named Qodex environment to run against.         |
| `tags`         | empty     | Tags to run. Empty means the full active suite. |
| `mode`         | `brief`   | Reporting mode echoed in the response.          |
| `callback_url` | none      | Optional URL Qodex calls when the run finishes. |

## Response

The trigger returns `202 Accepted` with a test run id.

```json theme={null}
{
  "testRunId": "run_01H8X3J4N5...",
  "status": "running",
  "scenariosTotal": 7,
  "mode": "brief"
}
```

Use the run id to open the run in Qodex or poll the test run endpoint until it completes.

## Poll or callback

Most CI systems should poll the run status and fail the job if Qodex reports failure.

```bash theme={null}
curl -H "Authorization: Bearer qk_xxx..." \
  https://agents.qodex.ai/api/projects/my-project-slug/test-runs/run_01H8X3J4N5...
```

If you provide `callback_url`, Qodex sends a completion payload with pass and fail counts plus the run URL.

## Per-schedule webhook

Use a schedule webhook when one external trigger should always run one preconfigured policy.

```text theme={null}
POST https://agents.qodex.ai/api/webhooks/schedules/<secret>
```

The secret in the URL is the authentication. This is useful when CI should fire a paused schedule without changing the schedule's cron state.

## Safety notes

* Store `qk_` keys in your CI secret store.
* Revoke old keys when rotating credentials.
* Calls with no runnable scenarios return an error instead of creating an empty run.
* Duplicate webhook calls create duplicate runs, so handle retry idempotency in the caller if needed.

## Related

<CardGroup cols={2}>
  <Card title="Run tests in CI" icon="git-branch" href="/run-tests-in-ci">
    Use webhooks as required checks in pipelines.
  </Card>

  <Card title="Run tests on a schedule" icon="calendar-clock" href="/run-tests-on-schedule">
    Create the policies used by schedule webhooks.
  </Card>
</CardGroup>