Generic webhook

Use a generic webhook when you want Qodex run results to flow into your own system. Common uses include sending results to Microsoft Teams, Discord, PagerDuty, a CI service, an internal dashboard, or a small relay that creates tickets.

Webhook options

Qodex can send outbound webhooks in two places:

Option	When it fires	Best for
Schedule webhook	After a scheduled run finishes.	Team notifications and recurring checks.
`callback_url` on a trigger request	After a webhook-triggered run finishes.	CI jobs that need a completion callback.

Both fire once when the run completes.

Qodex does not retry failed webhook deliveries today. Make your endpoint idempotent, return a 2xx response quickly, and use the run id to fetch details later if needed.

Schedule webhook

Add a webhook URL to a schedule in Schedules > Notifications. If the URL is not a Slack webhook URL, Qodex sends a generic JSON payload:

{
  "event": "test_run_completed",
  "projectName": "Acme Staging",
  "projectSlug": "acme-staging",
  "testRunId": "tr_...",
  "policy": { "id": "pol_...", "name": "Nightly regression" },
  "passed": false,
  "summary": { "total": 42, "passed": 39, "failed": 3 },
  "failedScenarios": [
    { "name": "Cancel order", "status": "fail" }
  ],
  "environment": "staging",
  "durationMs": 86420,
  "runUrl": "https://agents.qodex.ai/p/acme-staging/test-runs/tr_...",
  "timestamp": 1764979286420
}

Fields that do not apply to a run are sent as null or empty arrays, so consumers can rely on a stable shape.

Trigger callback URL

When you trigger a run from CI, include callback_url in the request body.

curl -X POST https://agents.qodex.ai/api/projects/acme-staging/webhooks/trigger \
  -H "Authorization: Bearer qk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "tags": ["smoke"],
    "callback_url": "https://ci.example.com/hooks/qodex/abc123"
  }'

Qodex responds immediately with a running test id. When the run finishes, Qodex posts a compact callback:

{
  "testRunId": "tr_...",
  "status": "passed",
  "total": 42,
  "passed": 42,
  "failed": 0,
  "url": "https://agents.qodex.ai/p/acme-staging/test-runs/tr_..."
}

Securing your endpoint

Outbound payload signing is not currently implemented. Protect the endpoint with one or more of these controls:

A long random path token.
A network allowlist.
A relay that validates the request before forwarding it.
Idempotency keyed by testRunId.

Troubleshooting

If your endpoint does not receive a payload:

Confirm the URL is reachable from the Qodex deployment.
Confirm the endpoint returns a 2xx response.
Check whether the schedule’s notification rule allows sending for that run.
Check server logs for webhook delivery failures.

Next steps

Run tests via webhook

Trigger a run and pass a completion callback.

Run tests on a schedule

Add a webhook URL to a recurring policy.

Slack

Use the Slack-formatted version of the same dispatcher.

Integrations

Return to all integrations.

Slack Bring your own key

Get started

Concepts

PR review

API testing

UI testing

Security testing

Run tests

Findings

Memory

Skills

Integrations

Self-hosted

Account

Generic webhook

Generic webhook

Webhook options

Schedule webhook

Trigger callback URL

Securing your endpoint

Troubleshooting

Next steps

Run tests via webhook

Run tests on a schedule

Slack

Integrations

​Generic webhook

​Webhook options

​Schedule webhook

​Trigger callback URL

​Securing your endpoint

​Troubleshooting

​Next steps

Run tests via webhook

Run tests on a schedule

Slack

Integrations

Generic webhook

Webhook options

Schedule webhook

Trigger callback URL

Securing your endpoint

Troubleshooting

Next steps