API endpointów webhook

Rejestruj endpointy HTTPS, aby otrzymywać podpisane HMAC POST-y zdarzeń, gdy w platformie dzieje się coś istotnego — otwarcie sesji, przechwycenie dowodu, zakotwiczenie łańcucha audytu. Każde dostarczenie jest ponawiane z wykładniczym backoffem, podpisywane sekretem per endpoint i zabezpieczone przed powtórzeniem przez 5-minutowe okno znacznika czasu.

Katalog zdarzeń + kształty ładunków znajdziesz w Przegląd webhooków. Ta strona to powierzchnia API do zarządzania endpointami + inspekcji prób dostarczenia.

Obiekt Endpoint

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

Uwaga: pole signing_secret jest zwracane dokładnie raz w odpowiedzi POST — zapisz je natychmiast lub później dokonaj rotacji przez PATCH, jeśli je utracisz.

Listowanie endpointów

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

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

Utworzenie endpointu

POST /api/v1/public/webhook-endpoints — zakres 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"]
  }'

Pola treści

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

signing_secret to klucz HMAC-SHA256, którym platforma podpisuje każdy POST. Zweryfikuj nagłówek NB-Signature po stronie odbiorcy — nasze SDK dostarczają jednolinijkowy helper.

Pobranie / aktualizacja / usunięcie

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

GET wymaga webhooks:read; PATCH + DELETE wymagają webhooks:write. PATCH przyjmuje ten sam kształt treści co POST — każde pole opcjonalne. Użyj go, aby wstrzymać endpoint ({"active": false}), zawęzić jego subskrypcję lub dokonać rotacji sekretu podpisującego.

Rotacja sekretu podpisującego

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

Nowy sekret jest zwracany dokładnie raz w treści odpowiedzi, w tym samym kształcie co przy wywołaniu tworzącym. Zarówno stary, jak i nowy sekret są ważne przez kolejne 24 h, aby dać odbiorcy czas na wdrożenie — po tym czasie stary zostaje unieważniony.

Inspekcja prób dostarczenia

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

Ostatnie 100 prób dostarczenia dla organizacji poświadczenia. Filtruj przez ?endpoint={id} lub ?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
}

Rytm ponawiania

Nieudane dostarczenia są ponawiane według tego harmonogramu, a następnie porzucane:

• +30 sekund
• +5 minut
• +1 godzina
• +6 godzin
• +24 godziny
• po tym czasie → dropped (widoczne w logu dostarczeń)

Typowe błędy