API des endpoints webhook

Enregistrez des endpoints HTTPS pour recevoir des POST d'événements signés HMAC dès qu'un événement notable se produit sur la plateforme — ouverture de sessions, capture de preuves, ancrage des chaînes d'audit. Chaque livraison est réessayée avec un backoff exponentiel, signée avec un secret propre à chaque endpoint, et protégée contre le rejeu par une fenêtre d'horodatage de 5 minutes.

Pour le catalogue d'événements + la forme des payloads, voir Vue d'ensemble des webhooks. Cette page décrit la surface d'API pour gérer les endpoints + inspecter les tentatives de livraison.

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

Remarque : le champ signing_secret est renvoyé exactement une fois dans la réponse du POST — stockez-le immédiatement, ou faites-le tourner plus tard via PATCH si vous le perdez.

Lister les endpoints

GET /api/v1/public/webhook-endpoints — Portée webhooks:read

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

Créer un endpoint

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

Champs du corps

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

Le signing_secret est la clé HMAC-SHA256 que la plateforme utilise pour signer chaque POST. Vérifiez l'en-tête NB-Signature côté récepteur — nos SDK fournissent un helper en une ligne.

Récupérer / mettre à jour / supprimer

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

GET requiert webhooks:read ; PATCH + DELETE requièrent webhooks:write. PATCH accepte la même forme de corps que POST — chaque champ est optionnel. Utilisez-le pour suspendre un endpoint ({"active": false}), restreindre son abonnement, ou faire tourner le secret de signature.

Faire tourner le secret de signature

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

Le nouveau secret est renvoyé exactement une fois dans le corps de la réponse, avec la même forme que l'appel de création. L'ancien + le nouveau secret sont tous deux valides pendant 24 h afin de laisser à votre récepteur le temps de déployer — passé ce délai, l'ancien est révoqué.

Inspecter les tentatives de livraison

GET /api/v1/public/webhook-events — Portée webhooks:read

Les 100 dernières tentatives de livraison pour l'organisation de l'identifiant. Filtrez par ?endpoint={id} ou ?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
}

Cadence de réessai

Les livraisons en échec sont réessayées selon ce calendrier, puis abandonnées :

• +30 secondes
• +5 minutes
• +1 heure
• +6 heures
• +24 heures
• après cela → dropped (visible dans le journal de livraison)

Erreurs courantes