Webhooks
Set up Qualflare project webhooks to get a signed HTTP POST when test results are uploaded or a defect is created, with payloads, headers and retries.
Last updated
Webhooks let you receive HTTP notifications from Qualflare when test results are uploaded to your project or a defect is created. Use webhooks to trigger custom automation, or to notify services that don't have a native integration.
Managing Webhooks
Webhooks are configured per project at Project Settings → Webhooks.
Creating a Webhook
You need the Editor role or higher on the project.
- Go to Project Settings → Webhooks
- Click Create Webhook
- Enter:
- Name — 3 to 100 characters
- Webhook URL — the HTTPS endpoint to receive the webhook payload
- Subscribe Events — which events should trigger this webhook (see Events below)
- Click Create
The webhook status badge shows Active when enabled.
Webhook Events
| Event | When It Fires |
|---|---|
launch.completed | Test results are uploaded to the project with the CLI, a reporter or the API, whatever the result. Manual runs don't send it. |
defect.created | A defect is created on the Defects page, or through the API or MCP. Qualflare also sends it when it opens a defect for a flaky test. Defects opened automatically for a failure cluster, and defects created from a redundant test notification, don't send it. |
Payload Format
Qualflare sends an HTTP POST request to your webhook URL with a JSON body. Example payload:
{
"event": "launch.completed",
"timestamp": 1775044800,
"project_id": "3f2c8a1e-5b7d-4c9e-8f10-2a6b4d9e7c31",
"data": {
"seq": 42,
"status": "failed",
"branch": "main"
}
}| Field | Description |
|---|---|
event | The event type, also sent as X-Webhook-Event |
timestamp | When Qualflare created the delivery, in Unix seconds. Retries keep the same value |
project_id | The project's ID, a UUID |
data.seq | The launch number |
data.status | The launch status: passed, failed, error, skipped, timeout, aborted or pending |
data.branch | The branch sent with the upload, or null if it had none |
For defect.created, the envelope is the same and data holds the new defect:
| Field | Description |
|---|---|
data.seq | The defect number |
data.name | The defect title |
data.severity | low, medium, high or critical |
data.description | The description, or an empty string |
data.status | The defect status, such as active |
data.category | unknown for a defect created on the Defects page or through the API or MCP, or flaky for a flaky-test defect |
data.environment | The environment name |
data.expected, data.actual | The expected and actual results |
Fields after data.category are left out when they're empty. A flaky-test defect has none of them.
Enabling and Disabling
Delete removes the webhook at once, with no confirmation. Its signing secret can't be recovered.
Open the ⋯ menu on a webhook row and choose Disable or Enable. The Status column shows Active or Disabled. Delete, in the same menu, deletes the webhook.
After you create a webhook, you can only disable or enable it. To change its name, URL or events, create a new webhook (it gets a new signing secret), then delete the old one.
Request Headers
Every webhook delivery includes:
| Header | Description |
|---|---|
Content-Type | Always application/json |
User-Agent | Astrais-Webhook/1.0 |
X-Webhook-Event | The event type that triggered this delivery (e.g. launch.completed) |
X-Webhook-ID | The webhook's own ID (a UUID, the same on every delivery). The app doesn't show it, so note it from the first delivery — useful for routing if one endpoint handles deliveries from multiple webhooks |
X-Webhook-Signature | HMAC-SHA256 signature of the raw request body — see Verifying Signatures below |
Only https:// endpoints are accepted (on port 443 or 8443), and the host must resolve to public IP addresses. Redirects aren't followed.
Delivery and retries. A delivery succeeds only when your endpoint returns a 2xx status within 20 seconds. Qualflare retries timeouts, connection errors and 5xx, 408, 425 and 429 responses, up to 10 attempts in total, 10 seconds to 5 minutes apart. It doesn't retry other responses. A retry sends the same body and signature, so make your receiver safe to call twice.
Verifying Signatures
Each webhook has its own signing secret, generated automatically and shown exactly once, in a banner at the top of the Webhooks page, right after you create it. Copy it before you leave the page — it can't be viewed again afterward (only regenerated by recreating the webhook). If you never saw a webhook's secret, recreate the webhook.
To verify a delivery is genuinely from Qualflare, compute an HMAC-SHA256 digest of the raw request body using your secret, and compare it — as a constant-time comparison, not === — against the X-Webhook-Signature header, which is formatted as sha256=<hex-digest>:
import crypto from 'node:crypto';
function isValidSignature(rawBody, signatureHeader, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
const received = Buffer.from(signatureHeader ?? '');
const wanted = Buffer.from(expected);
return received.length === wanted.length && crypto.timingSafeEqual(received, wanted);
}Sign the raw request body, not a re-serialized version of the parsed JSON — re-serializing can change key order or whitespace and produce a signature mismatch even for a legitimate delivery.
Security
Verify the X-Webhook-Signature header on every request as described above — this is the reliable way to confirm a delivery is genuinely from Qualflare, not just checking the payload shape or origin IP.
See Also
- Integrations Overview
- Integration events: what Slack, Jira and the other integrations send, and Recent deliveries
- CI/CD Integration
- Project Settings
- Changelog: What's new in Qualflare: October 2026
PagerDuty Integration
Connect Qualflare to PagerDuty to open incidents for new defects and failed launches, and resolve them when the defect closes or the branch passes again.
Qualflare API
The Qualflare REST API at api.qualflare.com/api/v1: authenticate with a project access token, page and sort lists, and find each endpoint and the MCP server.