Webhook-endpoints-API

Registreer HTTPS-endpoints om HMAC-ondertekende event-POSTs te ontvangen zodra er iets interessants gebeurt in het platform — sessies openen, bewijs wordt vastgelegd, audit chains verankeren. Elke aflevering wordt opnieuw geprobeerd met exponentiële backoff, ondertekend met een geheim per endpoint en replay-veilig via een tijdstempelvenster van 5 minuten.

Voor de event-catalogus + payload-vormen, zie Webhooks-overzicht. Deze pagina is de API om endpoints te beheren + afleverpogingen te inspecteren.

Het Endpoint-object

{
  "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"
}

Let op: het veld signing_secret wordt precies één keer teruggegeven in de POST-response — sla het meteen op, of roteer het later via PATCH als u het kwijtraakt.

Endpoints tonen

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

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

Een endpoint aanmaken

POST /api/v1/public/webhook-endpoints — scope 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-velden

{
  "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..."
}

De signing_secret is de HMAC-SHA256-sleutel waarmee het platform elke POST ondertekent. Verifieer de NB-Signature-header op uw ontvanger — onze SDK's leveren een one-liner-helper.

Ophalen / bijwerken / verwijderen

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

GET vereist webhooks:read; PATCH + DELETE vereisen webhooks:write. PATCH accepteert dezelfde body-vorm als POST — elk veld optioneel. Gebruik het om een endpoint te pauzeren ({"active": false}), het abonnement te versmallen of het signing secret te roteren.

Het signing secret roteren

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}'

Het nieuwe geheim wordt precies één keer teruggegeven in de response-body, dezelfde vorm als de create-call. Zowel het oude als het nieuwe geheim zijn de komende 24 u geldig zodat uw ontvanger tijd heeft om te deployen — daarna wordt het oude ingetrokken.

Afleverpogingen inspecteren

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

Laatste 100 afleverpogingen voor de org van de credential. Filter op ?endpoint={id} of ?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
}

Herpogingsritme

Mislukte afleveringen worden opnieuw geprobeerd volgens dit schema en vervallen daarna:

• +30 seconden
• +5 minuten
• +1 uur
• +6 uur
• +24 uur
• daarna → dropped (zichtbaar in de afleveringslog)

Veelvoorkomende fouten