Skip to main content

​
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:
OptionWhen it firesBest for
Schedule webhookAfter a scheduled run finishes.Team notifications and recurring checks.
callback_url on a trigger requestAfter 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.