API endpoint webhook

Registra endpoint HTTPS per ricevere POST di eventi firmati HMAC ogni volta che accade qualcosa di interessante nella piattaforma — le sessioni si aprono, le prove vengono acquisite, le catene di audit vengono ancorate. Ogni recapito viene ritentato con backoff esponenziale, firmato con un secret per endpoint ed è a prova di replay grazie a una finestra temporale di 5 minuti.

Per il catalogo degli eventi e le strutture dei payload, vedi Panoramica dei webhook. Questa pagina è la superficie API per gestire gli endpoint e ispezionare i tentativi di recapito.

L'oggetto 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"
}

Nota: il campo signing_secret viene restituito esattamente una volta nella risposta POST — memorizzalo subito, oppure ruotalo in seguito tramite PATCH se lo perdi.

Elenca gli endpoint

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

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

Crea un endpoint

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

Campi del 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..."
}

Il signing_secret è la chiave HMAC-SHA256 che la piattaforma usa per firmare ogni POST. Verifica l'header NB-Signature sul tuo ricevitore — i nostri SDK includono un helper in una riga.

Recupera / aggiorna / elimina

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

GET richiede webhooks:read; PATCH e DELETE richiedono webhooks:write. PATCH accetta la stessa struttura del body di POST — ogni campo è opzionale. Usalo per mettere in pausa un endpoint ({"active": false}), restringere la sua iscrizione o ruotare il signing secret.

Ruota il signing secret

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

Il nuovo secret viene restituito esattamente una volta nel body della risposta, con la stessa struttura della chiamata di creazione. Sia il vecchio che il nuovo secret sono validi per le successive 24 h per dare al tuo ricevitore il tempo di fare il deploy — dopodiché il vecchio viene revocato.

Ispeziona i tentativi di recapito

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

Ultimi 100 tentativi di recapito per l'org della credenziale. Filtra con ?endpoint={id} o ?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
}

Cadenza dei tentativi

I recapiti falliti vengono ritentati secondo questa pianificazione, poi scartati:

• +30 secondi
• +5 minuti
• +1 ora
• +6 ore
• +24 ore
• dopodiché → dropped (visibile nel log di recapito)

Errori comuni