Skip to content
The docs are now organized by product area. Old links still work. Report a broken link

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.

  1. Go to Project Settings → Webhooks
  2. Click Create Webhook
  3. 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)
  4. Click Create

The webhook status badge shows Active when enabled.

Webhook Events

EventWhen It Fires
launch.completedTest results are uploaded to the project with the CLI, a reporter or the API, whatever the result. Manual runs don't send it.
defect.createdA 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"
  }
}
FieldDescription
eventThe event type, also sent as X-Webhook-Event
timestampWhen Qualflare created the delivery, in Unix seconds. Retries keep the same value
project_idThe project's ID, a UUID
data.seqThe launch number
data.statusThe launch status: passed, failed, error, skipped, timeout, aborted or pending
data.branchThe 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:

FieldDescription
data.seqThe defect number
data.nameThe defect title
data.severitylow, medium, high or critical
data.descriptionThe description, or an empty string
data.statusThe defect status, such as active
data.categoryunknown for a defect created on the Defects page or through the API or MCP, or flaky for a flaky-test defect
data.environmentThe environment name
data.expected, data.actualThe 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:

HeaderDescription
Content-TypeAlways application/json
User-AgentAstrais-Webhook/1.0
X-Webhook-EventThe event type that triggered this delivery (e.g. launch.completed)
X-Webhook-IDThe 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-SignatureHMAC-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