Webhook events

When you configure webhooks, VisualQ sends HTTP POST requests to your endpoint for the events you subscribe to.

Event types

run.started

Fired when a test run begins.

{
  "event": "run.started",
  "projectId": "proj_xyz",
  "projectName": "My Website",
  "projectSlug": "my-website",
  "runId": "run_abc123",
  "runType": "vrt-test"
}

run.completed

Fired when a test run finishes successfully.

{
  "event": "run.completed",
  "projectId": "proj_xyz",
  "projectName": "My Website",
  "projectSlug": "my-website",
  "runId": "run_abc123",
  "runType": "vrt-test",
  "data": {
    "status": "completed",
    "total": 10,
    "passed": 8,
    "failed": 2
  }
}

run.failed

Fired when a test run encounters an error.

{
  "event": "run.failed",
  "projectId": "proj_xyz",
  "projectName": "My Website",
  "projectSlug": "my-website",
  "runId": "run_abc123",
  "runType": "vrt-test",
  "data": {
    "error": "Worker connection timeout"
  }
}

diff.detected

Fired when visual differences are found in a test run.

{
  "event": "diff.detected",
  "projectId": "proj_xyz",
  "projectName": "My Website",
  "projectSlug": "my-website",
  "runId": "run_abc123",
  "runType": "vrt-test",
  "data": {
    "total": 10,
    "passed": 8,
    "failed": 2
  }
}

scenario.approved

Fired when a scenario's visual changes are approved.

{
  "event": "scenario.approved",
  "projectId": "proj_xyz",
  "projectName": "My Website",
  "projectSlug": "my-website",
  "runId": "run_abc123",
  "data": {
    "scenarioLabel": "Homepage"
  }
}

ai.analysis.completed

Fired when a Smart Diff AI analysis finishes.

{
  "event": "ai.analysis.completed",
  "projectId": "proj_xyz",
  "projectName": "My Website",
  "projectSlug": "my-website",
  "runId": "run_abc123",
  "runType": "vrt-test"
}

Headers

All webhook requests include:

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`VisualQ-Webhook/1.0`
`X-VisualQ-Signature`	HMAC-SHA256 signature for verifying authenticity
`X-VisualQ-Event`	The event type (e.g., `run.completed`)
`X-VisualQ-Delivery`	Unique delivery identifier

See Webhooks for details on signature verification.

If your endpoint returns a 5xx status code or 429, VisualQ retries the delivery once (up to 2 total attempts). For other non-2xx codes, the delivery is not retried. Make sure your endpoint responds within 10 seconds.