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
  }
}

This event type is defined in the integration schema and can be selected in Settings, but it is not emitted yet when you approve changes from the dashboard. Subscribe only if you are building against a future release.

Expected payload when implemented:

{
  "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"
}

ai.analysis.completed is dispatched by the platform but is not yet selectable in Settings → Integrations. It will appear in the event picker in a future release.

quality_score.dropped

Fired when a Full audit completes and the composite Quality Score drops by 5 points or more compared to the previous score for the same project.

{
  "event": "quality_score.dropped",
  "projectId": "proj_xyz",
  "projectName": "My Website",
  "projectSlug": "my-website",
  "runId": "run_abc123",
  "runType": "vrt-test",
  "data": {
    "previousScore": 92,
    "newScore": 85,
    "delta": -7
  }
}

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.

Retry policy

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.

On this page