Docs · für Entwickler

Webhooks

Push-Benachrichtigungen für das, was Ihre Systeme interessiert: ein abgeschlossener Scan, ein neuer Tracker, eine veröffentlichte Version, ein fertiger Nachweis-Export. Signiert, wiederholt und einsehbar.

Endpunkte

Erstellen Sie Endpunkte unter Workspace-Einstellungen → Entwickler → Webhooks oder über die API. Nur https-URLs auf öffentlichen Hosts werden akzeptiert; private und interne Adressen werden bei der Registrierung abgelehnt. Das Signiergeheimnis (whsec_…) wird bei der Erstellung einmal gezeigt und kann jederzeit rotiert werden; nach einer Rotation prüfen Sie gegen beide Geheimnisse, bis Ihr Deploy nachgezogen hat.

Events

Zwölf Ereignistypen, einzeln oder mit * abonnierbar:

scan.completed · scan.failed · tracker.new · issue.opened · issue.resolved · alert.raised · config.published · version.promoted · export.completed · declaration.updated · install.broken · plan.changed

Eine Zustellung verifizieren

Zustellungen folgen der Standard-Webhooks-Konvention. Drei Header kommen mit jedem POST:

webhook-id:        <delivery id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64(hmac_sha256(key, id.timestamp.body))>

Der HMAC-Schlüssel ist der base64-Teil Ihres whsec_-Geheimnisses, in Rohbytes dekodiert. Berechnen Sie die Signatur über id + "." + timestamp + "." + body neu, vergleichen Sie in konstanter Zeit und weisen Sie alles ab, was älter als fünf Minuten ist:

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

function verify(secret, headers, rawBody) {
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const msg = headers['webhook-id'] + '.' + headers['webhook-timestamp'] + '.' + rawBody;
  const want = createHmac('sha256', key).update(msg).digest();
  const got = Buffer.from(headers['webhook-signature'].split(',')[1], 'base64');
  const fresh = Math.abs(Date.now() / 1000 - Number(headers['webhook-timestamp'])) < 300;
  return fresh && want.length === got.length && timingSafeEqual(want, got);
}

Wiederholungen und erneute Zustellung

Eine fehlgeschlagene Zustellung wird mit Backoff wiederholt: 1 Minute, dann 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden; danach wird sie als tot markiert. Jeder Versuch, Antwortcode und nächste Wiederholung ist im Zustellungsprotokoll des Endpunkts sichtbar, und jede Zustellung kann von Hand erneut gesendet werden; eine erneute Zustellung verweist auf das Original. Die Zustellungshistorie wird 90 Tage aufbewahrt.

Antworten

Antworten Sie schnell mit einem beliebigen 2xx und erledigen Sie die eigentliche Arbeit asynchron; alles andere zählt als Fehler und plant eine Wiederholung. Zustellungen können in falscher Reihenfolge und selten mehrfach eintreffen; nutzen Sie webhook-id für Idempotenz.