Webhooks and REST API

Webhooks tell your own systems when an analysis ends, a quality gate changes or new vulnerabilities are found, for example to open a ticket or feed a dashboard. The REST API lets scripts read and change what Qualor holds.

Webhooks

Org admins create a webhook in Settings → Webhooks with New webhook. Its Applies to field is All projects or one project. A webhook for one project is also listed under Project → Settings → Webhooks, where New webhook creates one for that project. Through the API, send projectId to POST /api/v0/webhooks. An organisation has at most 50 webhooks, counting project, Slack and Teams webhooks.

The type Generic (signed JSON) posts JSON to a receiver of your own, as described below. The types Slack and Microsoft Teams send formatted messages about the main branch’s quality gate, exploited vulnerabilities and a weekly security digest (Slack and Microsoft Teams). They have no secret and send no X-Qualor-* headers.

A generic webhook sends the events you choose:

The payload of analysis.completed and gate.status_changed is the analysis as GET /api/v0/analyses/{id} returns it: status, revision, gate status and result, engines and warnings. It also carries project (id, key, name) and branch (id, kind, name, isMain). For gate.status_changed it adds previousGateStatus. A tag scan sends no webhook, so the payload’s version is always null (Releases and versions).

The payload of vulnerabilities.found lists what the project’s digest lists, worst first:

{
  "project": {
    "id": "0190f6b0-7a4e-7c3a-9b1d-2f6e8a1c4d55",
    "key": "acme/payments",
    "name": "Payments",
    "url": "https://qualor.example.com/projects/0190f6b0-7a4e-7c3a-9b1d-2f6e8a1c4d55/vulnerabilities"
  },
  "database": { "builtAt": "2026-11-09T18:12:04.000Z" },
  "vulnerabilities": [
    {
      "vulnerabilityId": "CVE-2026-1001",
      "severity": "critical",
      "title": "Remote code execution in axios",
      "packageName": "axios",
      "installedVersions": ["1.7.2"],
      "fixedVersion": "1.7.4",
      "exploited": { "dateAdded": "2026-10-30" },
      "targets": ["main", "2.3.4"]
    }
  ],
  "more": 0
}

A project with nothing new sends no delivery.

Every request is a POST with a JSON body and these headers:

Verify the signature over the raw body, and reject old timestamps:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, headers, secret, maxAgeSeconds = 300) {
  const ts = headers['x-qualor-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > maxAgeSeconds) return false;
  const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const given = String(headers['x-qualor-signature'] ?? '');
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

The secret. Qualor generates it (whsec_…) and shows it once, when the webhook is created. Through the API you can send your own secret instead, 16 to 256 characters, to POST /api/v0/webhooks or PATCH /api/v0/webhooks/{id}. Qualor then returns none. To have a new one generated, press Rotate secret on the webhook (API: POST /api/v0/webhooks/{id}/regenerate-secret). The old secret stops signing at once, so update the receiver with the new one, which is also shown once.

Delivery. Each attempt has 10 s to complete. A delivery gets 7 attempts, with backoff of 1, 2, 4, 8, 16 and 32 minutes between them. Only a 2xx answer counts as success, and redirects are not followed.

Failures. When a delivery gives up after its 7 attempts, instance administrators get an email (Email), at most one a day for each webhook. Organisation administrators get the same email for their organisation’s webhooks, unless they turned it off in Settings → Notifications (Email). A webhook that is switched off alerts nobody.

History. Each webhook shows its last 20 deliveries as a strip, with the share delivered: delivered above the line, failed below it, pending on it. Recent deliveries lists them with each one’s status, response code and the first 1 KiB of the answer. Deliveries are kept 30 days. Refresh reloads the list. Send again sends a delivery once more (API: POST /api/v0/webhooks/{id}/deliveries/{deliveryId}/redeliver).

Receiver addresses. Webhook URLs must be https and resolve to public addresses. To allow http or internal receivers, such as a chat bot on the intranet, an operator sets the instance setting in PostgreSQL:

INSERT INTO instance_settings (key, value) VALUES ('webhooks', '{"allowInternalHosts": true, "allowHttp": false}')
ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now();

Audit event streaming (enterprise)

With a licence that lists audit-log and audit-log.stream (the Enterprise plan), Settings → Audit settings configures a stream that posts new audit events to a SIEM as they are recorded. There is one stream per instance, with its own URL and its own secret. A delivery carries X-Qualor-Event: audit.events and the same X-Qualor-Timestamp and X-Qualor-Signature headers as a webhook, verified the same way. A batch can be sent again after a timeout, so deduplicate on each event’s seq. The body, the retries, what is never sent and the Business plan’s behaviour are in Streaming to a SIEM.

REST API

The API lives under /api/v0. It is JSON over HTTPS, described by OpenAPI 3.1 in server/openapi.json. Authenticate with Authorization: Bearer <token>. Version 0 can change between releases.

The MCP server and its OAuth sign-in endpoints (/mcp, /oauth/* and /.well-known/*) are outside /api/v0. Their tokens belong to the app a person allowed and work only on /mcp. They are not API tokens, and an API token does not work on /mcp.

export QUALOR_URL=https://qualor.example.com QUALOR_TOKEN=qlr_pat_…
q() { curl -fsS -H "Authorization: Bearer $QUALOR_TOKEN" -H 'Content-Type: application/json' "$@"; }

q "$QUALOR_URL/api/v0/projects?q=payments"                        # find projects
q "$QUALOR_URL/api/v0/projects/by-key?key=acme/payments-api"      # one project, with its main branch
q "$QUALOR_URL/api/v0/projects/<id>/branches"                     # branches and MRs with gate status
q "$QUALOR_URL/api/v0/branches/<id>/measures?metrics=coverage,ncloc"
q "$QUALOR_URL/api/v0/issues?branchId=<id>&severity=blocker&severity=high&inNewCode=true"

Errors are application/problem+json with a stable code, such as PROJECT_NOT_FOUND, INSUFFICIENT_SCOPE, INVALID_TRANSITION or AI_QUOTA_EXCEEDED. The API answers 404 for resources you cannot see, and 403, with a code that says why, for resources you can see but not change.

GET /auth/me and every project answer (GET /projects, GET /projects/{id}, GET /projects/by-key) carry the caller’s effective permissions for that organisation or project, so a script can tell what it may do without trying. /auth/me also lists the caller’s own projectGrants across every organisation, at most 1 000 of them.

Example: mark issues as false positives in bulk:

q -X POST "$QUALOR_URL/api/v0/issues/bulk-transition" \
  -d '{"ids":["<issue id>","<issue id>"],"to":"false_positive","comment":"Generated code, see ADR-12"}'

SBOM and VEX export (enterprise)

GET /projects/sbom and GET /projects/vex download a file for a branch or a version. They need the sbom feature (403 FEATURE_NOT_LICENSED without it).

A project analysis token reads the SBOM and VEX of its own project and no other project’s, so a release job needs no personal token. A person needs read access to the project.

curl -fsS -G -H "Authorization: Bearer $QUALOR_PROJECT_TOKEN" -OJ \
  --data-urlencode "projectKey=acme/payments-api" --data-urlencode "version=$RELEASE_TAG" \
  --data-urlencode "format=spdx" "$QUALOR_URL/api/v0/projects/sbom"
curl -fsS -G -H "Authorization: Bearer $QUALOR_PROJECT_TOKEN" -OJ \
  --data-urlencode "projectKey=acme/payments-api" --data-urlencode "version=$RELEASE_TAG" \
  --data-urlencode "format=openvex" "$QUALOR_URL/api/v0/projects/vex"

Searching users

GET /users/search?q= suggests people for the user name fields of the app. It answers active users whose user name starts with q, or one of whose display name’s words does, ignoring case, ordered by user name. Each user has only id, username and displayName, never an email address.

It needs what GET /users/lookup needs: a token with the Admin scope, of an instance admin or of someone who manages the members of an organisation. An excluded organisation or project answers 403 when the caller can see it but not manage it, and 404 when they cannot see it. Each caller gets 60 searches a minute (429 RATE_LIMITED beyond that). GET /users/lookup has its own 30.

curl -fsS -H "Authorization: Bearer $QUALOR_ADMIN_TOKEN" \
  "$QUALOR_URL/api/v0/users/search?q=smi&excludeOrganization=<org id>"

Single sign-on and SCIM (enterprise)

Instance admins manage single sign-on through these endpoints, below /api/v0, with a session or a personal token with the Admin scope (Single sign-on and SCIM). They need a licence that lists sso. Several enabled connections need sso.multi, and SCIM needs scim: both are in the Enterprise plan only. Secrets are write-only: an answer says only whether one is set (clientSecretSet, spKeySet).

The browser flows (/ee/sso/{id}/start, /ee/sso/oidc/{id}/callback, /ee/sso/saml/{id}/acs, /ee/sso/finish) and Qualor’s public SAML metadata (/ee/sso/saml/{id}/metadata) are for the browser and the IdP, not for scripts. A failed flow ends on the sign-in page with ?sso_error=<code> (Troubleshooting).

Example: list the sign-in methods (no token needed):

curl -fsS "$QUALOR_URL/api/v0/auth/methods"