Zuverlässige Signale für Arbeit, die Zeit braucht

Einen Endpunkt registrieren

Ergänze einen Endpunkt auf der Seite Entwickler oder mit dem Berechtigungsbereich webhooks:write:

curl -s -X POST "$BASE/workspaces/$WS/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/mini-casa","events":["job.updated","publication.updated"]}'

Die Antwort enthält signing_secret (whsec_...), das einmal angezeigt wird. Die URL muss HTTPS auf Port 443 nutzen und ausschließlich zu öffentlichen Adressen auflösen. Private, Loopback- und interne Ziele werden abgelehnt. Die Prüfung läuft vor jeder Zustellung erneut; Weiterleitungen werden nie verfolgt. Ein Arbeitsbereich darf bis zu 10 aktive Endpunkte haben.

Deine Kontrolle nachweisen

Neue Endpunkte beginnen als pending_verification. Die Schaltfläche Verifizieren oder POST /webhooks/{id}/verify sendet eine signierte webhook.challenge. Antworte mit 2xx und {"challenge": "<data.challenge>"}, damit der Endpunkt active wird.

Ereignisse

• job.updated: Ein Auftrag oder Stapellauf ändert seinen Zustand.
• job.item.updated: Ein einzelner Stapellaufeintrag ändert seinen Zustand.
• domain.updated: Eine eigene Domain durchläuft ihre Prüfungen.
• publication.updated: Ein Build startet, gelingt, scheitert oder wird ersetzt.
• approval.updated: Eine Genehmigung wird entschieden, läuft ab oder wird verwendet.
• billing.entitlement.updated: Tarif oder Berechtigungen ändern sich.

Anfrageinhalte tragen nur Kennungen und einen Zustand, niemals Zugangsdaten, Inhalte oder persönliche Daten. Rufe den aktuellen Zustand über die API ab.

Jede Anfrage prüfen

Jede Anfrage enthält SmallWorld-Webhook-Id, SmallWorld-Webhook-Timestamp (Unix-Sekunden) und SmallWorld-Webhook-Signature (v1=<hex>,kid=<key id>). Die Signatur ist HMAC-SHA256 von <timestamp>.<raw body> mit deinem Geheimnis. Nutze den unverarbeiteten Inhalt vor jedem JSON-Parsing, vergleiche in konstanter Zeit und lehne Zeitstempel ab, die mehr als fünf Minuten von deiner Uhr abweichen.

import crypto from "node:crypto";

export function verify(secret, timestamp, rawBody, header) {
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = /v1=([a-f0-9]+)/.exec(header)?.[1] ?? "";
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  return fresh && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Zustellungsgarantien

• Mindestens einmal. Eine Anfrage wiederholt sich, bis du mit 2xx antwortest. Die Ereigniskennung bleibt bei jedem erneuten Versuch und jeder Neuzustellung gleich. Speichere sie und ignoriere bereits bekannte Kennungen.
• Die Wiederholungsabstände wachsen von einer Minute auf einen Tag, insgesamt über 72 Stunden. Danach ist die Zustellung unzustellbar. Du kannst sie auf der Entwicklerseite oder mit redeliver_webhook erneut senden.
• Ein Endpunkt mit 10 aufeinanderfolgenden unzustellbaren Ereignissen wird pausiert, bis du ihn fortsetzt.
• Die Reihenfolge ist nicht garantiert. Behandle den Zustand als Hinweis und lies die Ressource.