API webhook endpointů

Registrujte HTTPS endpointy pro příjem HMAC-podepsaných POSTů událostí, kdykoli se na platformě stane něco zajímavého — otevřou se relace, zachytí se důkaz, ukotví se auditní řetězec. Každé doručení se opakuje s exponenciálním backoffem, podepisuje se tajným klíčem specifickým pro daný endpoint a je odolné vůči replay útokům díky 5minutovému oknu časového razítka.

Katalog událostí + tvary payloadů najdete v Přehled webhooků. Tato stránka je API rozhraní pro správu endpointů + kontrolu pokusů o doručení.

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

Poznámka: pole signing_secret se vrací právě jednou v odpovědi na POST — okamžitě si jej uložte, nebo jej později rotujte přes PATCH, pokud jej ztratíte.

Výpis endpointů

GET /api/v1/public/webhook-endpoints — oprávnění webhooks:read

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

Vytvoření endpointu

POST /api/v1/public/webhook-endpoints — oprávnění 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"]
  }'

Pole těla požadavku

{
  "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 je klíč HMAC-SHA256, kterým platforma podepisuje každý POST. Na svém přijímači ověřte hlavičku NB-Signature — naše SDK přinášejí jednořádkový pomocník.

Načtení / aktualizace / smazání

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

GET vyžaduje webhooks:read; PATCH + DELETE vyžadují webhooks:write. PATCH přijímá stejný tvar těla jako POST — každé pole je volitelné. Použijte jej k pozastavení endpointu ({"active": false}), zúžení jeho odběru nebo rotaci podpisového tajného klíče.

Rotace podpisového tajného klíče

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

Nový tajný klíč se vrací právě jednou v těle odpovědi, ve stejném tvaru jako u volání pro vytvoření. Starý i nový tajný klíč jsou platné dalších 24 h, aby měl váš přijímač čas na nasazení — poté je starý zneplatněn.

Kontrola pokusů o doručení

GET /api/v1/public/webhook-events — oprávnění webhooks:read

Posledních 100 pokusů o doručení pro organizaci daného přístupového klíče. Filtrujte pomocí ?endpoint={id} nebo ?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
}

Kadence opakování

Neúspěšná doručení se opakují podle tohoto rozvrhu, poté se zahodí:

• +30 sekund
• +5 minut
• +1 hodina
• +6 hodin
• +24 hodin
• poté → dropped (viditelné v protokolu doručení)

Běžné chyby