# Webhooks

Source: https://docs.qualflare.com/docs/integrations/webhooks · Last updated: 2026-11-09

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.

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

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

```json
{
  "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

> **Caution:** **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.

> **Warning:** 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>`:

```javascript
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);
}
```

> **Warning:** 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](https://docs.qualflare.com/docs/integrations)
* [Integration events](https://docs.qualflare.com/docs/integrations/events): what Slack, Jira and the other integrations send, and Recent deliveries
* [CI/CD Integration](https://docs.qualflare.com/docs/cli/ci-cd)
* [Project Settings](https://docs.qualflare.com/docs/administration/project-settings)
* Changelog: [What's new in Qualflare: October 2026](https://changelog.qualflare.com/october-2026)
