Skip to main content

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

FieldDefaultMeaning
environmentstagingNamed Qodex environment to run against.
tagsemptyTags to run. Empty means the full active suite.
modebriefReporting mode echoed in the response.
callback_urlnoneOptional URL Qodex calls when the run finishes.

​
Response

The trigger returns 202 Accepted with a test run id. 
{
  "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. 
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. 
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.

Run tests in CI

Use webhooks as required checks in pipelines.

Run tests on a schedule

Create the policies used by schedule webhooks.