Webhooks

Starter plan

Webhooks let you receive HTTP POST requests when events occur in VisualQ. Use them to integrate with custom tools, dashboards, or automation systems.

Setup

Go to Integrations

Navigate to Settings > Integrations in your project.

Add a webhook

Click the Webhooks card and enter your webhook URL.

Select events

Choose which events trigger the webhook:

run.started
run.completed
run.failed
diff.detected
scenario.approved

Payload format

Webhook requests are POST with a JSON body containing a flat payload structure:

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

The runType field reflects the run type (vrt-test, perf-test, seo-test, tracking-test, baseline). Additional fields like ci and environmentId may be present depending on the run context.

Signature verification

All webhook requests include security headers for verifying authenticity:

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`VisualQ-Webhook/1.0`
`X-VisualQ-Signature`	HMAC-SHA256 signature (`sha256=...`) using your shared secret
`X-VisualQ-Event`	The event type (e.g., `run.completed`)
`X-VisualQ-Delivery`	Unique delivery ID

To verify the signature, compute the HMAC-SHA256 of the raw request body using your shared secret and compare it with the value in X-VisualQ-Signature.

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.

Best practices

Respond with a 2xx status code within 10 seconds
Use HTTPS endpoints for security
Implement idempotency — the same event may be delivered more than once
Verify the webhook source using the X-VisualQ-Signature header