Webhook-Endpunkte-API

Registrieren Sie HTTPS-Endpunkte, um HMAC-signierte Event-POSTs zu empfangen, sobald auf der Plattform etwas Relevantes geschieht — Sitzungen öffnen sich, Beweise werden erfasst, Audit-Ketten werden verankert. Jede Zustellung wird mit exponentiellem Backoff wiederholt, mit einem Secret pro Endpunkt signiert und über ein 5-Minuten-Zeitstempelfenster replay-sicher gemacht.

Den Event-Katalog + die Payload-Strukturen finden Sie unter Webhooks-Übersicht. Diese Seite ist die API-Oberfläche, um Endpunkte zu verwalten + Zustellversuche einzusehen.

Das Endpoint-Objekt

{
  "id": "we-1f2a...",
  "url": "https://hooks.acme.com/cvp",
  "description": "Production claims pipeline",
  "event_types": ["session.completed", "evidence.created"],
  "active": true,
  "created_at": "2026-04-12T09:00:00Z"
}

Hinweis: Das Feld signing_secret wird in der POST-Antwort genau einmal zurückgegeben — speichern Sie es sofort oder rotieren Sie es später per PATCH, falls Sie es verlieren.

Endpunkte auflisten

GET /api/v1/public/webhook-endpoints — Bereich webhooks:read

curl https://app.nexbasira.com/api/v1/public/webhook-endpoints \
  -H "Authorization: Bearer nb_sec_..."

Einen Endpunkt erstellen

POST /api/v1/public/webhook-endpoints — Bereich webhooks:write

curl -X POST https://app.nexbasira.com/api/v1/public/webhook-endpoints \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.acme.com/cvp",
    "description": "Production claims pipeline",
    "event_types": ["session.completed", "evidence.created"]
  }'

Body-Felder

{
  "id": "we-1f2a...",
  "url": "https://hooks.acme.com/cvp",
  "description": "Production claims pipeline",
  "event_types": ["session.completed", "evidence.created"],
  "active": true,
  "created_at": "2026-04-12T09:00:00Z",
  "signing_secret": "whsec_4f9d2a8b3c1e..."
}

Das signing_secret ist der HMAC-SHA256-Schlüssel, mit dem die Plattform jeden POST signiert. Verifizieren Sie den NB-Signature-Header auf Ihrem Empfänger — unsere SDKs liefern einen Einzeiler-Helper.

Abrufen / aktualisieren / löschen

GET / PATCH / DELETE /api/v1/public/webhook-endpoints/{endpoint_id}

GET benötigt webhooks:read; PATCH + DELETE benötigen webhooks:write. PATCH akzeptiert dieselbe Body-Struktur wie POST — jedes Feld optional. Damit pausieren Sie einen Endpunkt ({"active": false}), grenzen sein Abonnement ein oder rotieren das Signing-Secret.

Das Signing-Secret rotieren

curl -X PATCH https://app.nexbasira.com/api/v1/public/webhook-endpoints/we-1f2a... \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -d '{"rotate_secret": true}'

Das neue Secret wird genau einmal im Response-Body zurückgegeben, in derselben Struktur wie beim Create-Aufruf. Sowohl das alte als auch das neue Secret sind für die nächsten 24 h gültig, damit Ihr Empfänger Zeit zum Deployen hat — danach wird das alte widerrufen.

Zustellversuche einsehen

GET /api/v1/public/webhook-events — Bereich webhooks:read

Die letzten 100 Zustellversuche für die Organisation des Credentials. Filtern über ?endpoint={id} oder ?status=pending|delivered|failed|dropped.

{
  "data": [{
    "id": "wev-9a01...",
    "endpoint": "we-1f2a...",
    "event_type": "session.completed",
    "status": "delivered",
    "response_status": 200,
    "attempt_count": 1,
    "created_at": "2026-05-23T10:32:00Z",
    "delivered_at": "2026-05-23T10:32:01Z"
  }],
  "has_more": false,
  "next_cursor": null
}

Wiederholungsrhythmus

Fehlgeschlagene Zustellungen werden nach diesem Zeitplan wiederholt und dann verworfen:

• +30 Sekunden
• +5 Minuten
• +1 Stunde
• +6 Stunden
• +24 Stunden
• danach → dropped (im Zustellprotokoll sichtbar)

Häufige Fehler