Webhook-endpointtien API

Rekisteröi HTTPS-endpointteja vastaanottaaksesi HMAC-allekirjoitettuja tapahtuma-POSTeja aina, kun alustalla tapahtuu jotain kiinnostavaa — istuntoja avataan, todisteita kaapataan, auditointiketjuja ankkuroidaan. Jokainen toimitus yritetään uudelleen eksponentiaalisella backoffilla, allekirjoitetaan endpoint-kohtaisella salaisuudella ja on toistoturvallinen 5 minuutin aikaleimaikkunan ansiosta.

Tapahtumaluettelon ja payload-muotojen osalta katso Webhookien yleiskatsaus. Tämä sivu on API-pinta endpointtien hallintaan ja toimitusyritysten tarkasteluun.

Endpoint-objekti

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

Huomio: signing_secret-kenttä palautetaan täsmälleen kerran POST-vastauksessa — tallenna se heti tai kierrätä myöhemmin PATCH-kutsulla, jos hukkaat sen.

Listaa endpointit

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

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

Luo endpoint

POST /api/v1/public/webhook-endpoints — laajuus 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-kentät

{
  "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 on HMAC-SHA256-avain, jolla alusta allekirjoittaa jokaisen POSTin. Varmenna NB-Signature-otsake vastaanottimessasi — SDK:mme toimittavat yhden rivin apufunktion.

Hae / päivitä / poista

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

GET vaatii webhooks:read; PATCH ja DELETE vaativat webhooks:write. PATCH hyväksyy saman body-muodon kuin POST — jokainen kenttä valinnainen. Käytä sitä endpointin keskeyttämiseen ({"active": false}), sen tilauksen kaventamiseen tai allekirjoitussalaisuuden kierrättämiseen.

Kierrätä allekirjoitussalaisuus

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

Uusi salaisuus palautetaan täsmälleen kerran vastauksen bodyssä, samassa muodossa kuin luontikutsussa. Sekä vanha että uusi salaisuus ovat voimassa seuraavat 24 h, jotta vastaanottimesi ehtii ottaa käyttöön — sen jälkeen vanha kumotaan.

Tarkastele toimitusyrityksiä

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

Tunnuksen organisaation 100 viimeisintä toimitusyritystä. Suodata ?endpoint={id}- tai ?status=pending|delivered|failed|dropped-parametrilla.

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

Uudelleenyritysrytmi

Epäonnistuneet toimitukset yritetään uudelleen tämän aikataulun mukaan, sitten pudotetaan:

• +30 sekuntia
• +5 minuuttia
• +1 tunti
• +6 tuntia
• +24 tuntia
• sen jälkeen → dropped (näkyy toimituslokissa)

Yleiset virheet