API endpoint-uri Webhook

Înregistrați endpoint-uri HTTPS pentru a primi POST-uri de evenimente semnate HMAC ori de câte ori se întâmplă ceva important pe platformă — sesiunile se deschid, probele sunt capturate, lanțurile de audit se ancorează. Fiecare livrare este reîncercată cu revenire exponențială, semnată cu un secret per endpoint și protejată împotriva redării printr-o fereastră de 5 minute.

Pentru catalogul de evenimente + formele payload, consultați Prezentare generală Webhooks. Această pagină reprezintă suprafața API pentru gestionarea endpoint-urilor + inspecția tentativelor de livrare.

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

Notă: câmpul signing_secret este returnat o singură dată în răspunsul POST — stocați-l imediat sau rotiți-l ulterior prin PATCH dacă îl pierdeți.

Listare endpoint-uri

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

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

Creați un endpoint

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

Câmpuri body

{
  "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 este cheia HMAC-SHA256 pe care platforma o folosește pentru a semna fiecare POST. Verificați antetul NB-Signature pe receptorul dvs. — SDK-urile noastre includ un helper de o singură linie.

Preluare / actualizare / ștergere

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

GET necesită webhooks:read; PATCH + DELETE necesită webhooks:write. PATCH acceptă același format de body ca POST — fiecare câmp este opțional. Folosiți-l pentru a pausa un endpoint ({"active": false}), a restrânge abonamentul sau a roti secretul de semnare.

Rotiți secretul de semnare

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

Noul secret este returnat o singură dată în body-ul răspunsului, cu același format ca la creare. Atât secretul vechi cât și cel nou sunt valide pentru următoarele 24 h pentru a permite receptorului timp de deployment — după aceea, cel vechi este revocat.

Inspectați tentativele de livrare

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

Ultimele 100 tentative de livrare pentru organizația credențialei. Filtrați prin ?endpoint={id} sau ?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
}

Cadență de reîncercare

Livrările eșuate sunt reîncercate conform acestui program, apoi renunțate:

• +30 secunde
• +5 minute
• +1 oră
• +6 ore
• +24 ore
• după aceea → dropped (vizibil în jurnalul de livrare)

Erori frecvente