Configuration des webhooks

Les webhooks permettent à Certivant de transmettre en temps réel les changements d'état à votre backend. Au lieu d'interroger GET /requests/:id jusqu'à la fin du traitement, Certivant envoie une requête POST vers une URL que vous contrôlez chaque fois qu'un événement pertinent se produit.

Cette page couvre la configuration initiale, à faire une seule fois. Pour la vérification de signature à mettre en œuvre avant la mise en production, voir Vérification de la signature.

De quoi vous aurez besoin

• Une URL HTTPS accessible publiquement, qui accepte des requêtes POST avec un corps JSON. Localhost convient en développement si vous utilisez un tunnel (ngrok, Cloudflare Tunnel, tailscale funnel).
• Le rôle Propriétaire ou Administrateur dans l'organisation Certivant — les membres ne peuvent pas modifier les paramètres de webhook.
• Un moyen de conserver les secrets — vous obtiendrez un secret de signature HMAC que vous devez garder avec vos autres identifiants de production.

1 — Créer votre point de terminaison

Un gestionnaire minimal ressemble à ceci (Node + Hono illustré ; n'importe quel framework fonctionne) :

app.post("/webhooks/certivant", async (c) => {
  const body = await c.req.text();   // Read RAW body — needed for signature check
  const signature = c.req.header("X-Certivant-Signature-V2");
  const payload = JSON.parse(body);

  // Connectivity ping (the dashboard "Test" button) — ack immediately.
  // It carries `test: true` and mutates nothing, so no signature is required.
  if (payload.test === true || payload.event === "kyc.webhook.test") {
    return c.json({ ok: true }, 200);
  }

  // Verify the signature BEFORE trusting a real event, and reject if it fails.
  // See /developer/webhooks/signature-verification for the verify helper
  // (checks `t=<unix>,v1=<hex>` over `${t}.${body}`, 300 s tolerance).
  if (!verifyCertivantSignature(body, signature, process.env.CERTIVANT_WEBHOOK_SECRET!)) {
    return c.json({ error: "invalid signature" }, 401);
  }

  // Acknowledge fast — Certivant will retry if you take > 10s
  c.executionCtx.waitUntil(handlePayload(payload));
  return c.json({ received: true }, 200);
});

Les deux règles non négociables :

1. Répondez par un code 2xx dans les 10 secondes. Certivant considère tout le reste (5xx, 4xx, délai dépassé, erreur de connexion) comme un échec de livraison et réessaie avec un espacement exponentiel.
2. Lisez le corps brut avant d'analyser le JSON. La vérification de signature calcule un haché de la chaîne d'octets exacte envoyée par Certivant. Si votre framework analyse d'abord le JSON, vous reconstruirez une chaîne différente et la signature ne correspondra pas.

2 — Configurer l'URL dans le tableau de bord

3 — Envoyer un événement de test

Deux boutons vous aident à vérifier l'intégration :

• Tester (à côté de l'URL du webhook) envoie un ping de connectivité léger kyc.webhook.test portant test: true. Il confirme seulement que votre point de terminaison est accessible et renvoie 2xx : il n'a besoin d'aucune donnée de demande et fonctionne même avant que vous n'ayez conservé un secret de signature. Accusez-en réception immédiatement (voir le gestionnaire ci-dessus).

• Envoyer un événement de test (KYC → Développeur → Événements webhook) vous permet de choisir l'événement — le ping kyc.webhook.test ou une charge utile exemple kyc.request.created / approved / rejected / escalated — et l'envoie en POST signé exactement comme une livraison réelle (X-Certivant-Signature-V2 ainsi que les en-têtes X-KYC-*, horodatage Unix, votre secret de webhook). Les charges utiles exemples portent "test": true et un faux requestId. Utilisez-le pour :

• Confirmer que l'URL est accessible depuis l'infrastructure de Certivant.

• Confirmer que votre vérification de signature accepte une signature valide.

• Voir la forme exacte de la charge utile avant que des événements réels ne se déclenchent.

Vous pouvez aussi déclencher un test par programme, utile si vous voulez automatiser les tests de votre intégration :

curl -X POST https://app.certivant.com/api/kyc/settings/webhook-test \
  -H "Cookie: better-auth.session_token=..." \
  -H "Content-Type: application/json" \
  -d '{"event":"kyc.request.approved"}'
# returns { status: 200, latencyMs: 142, event, signed: true, headers: [...], responsePreview } if your endpoint replied

Le corps est facultatif (par défaut kyc.webhook.test). Ce point de terminaison utilise un cookie de session, et non une clé d'API : il s'agit d'une action côté tableau de bord.

4 — Renouveler le secret de signature

Lorsqu'un secret est exposé (ou une fois par an, par bonne hygiène) :

Il n'existe aucune période de chevauchement côté émetteur : les nouvelles livraisons ne sont signées qu'avec le nouveau secret. Les recettes de vérification de la vérification de la signature acceptent une liste de secrets et plusieurs valeurs v1=. Vous pouvez donc déployer, avant de renouveler, un vérificateur qui fait confiance à l'ancien comme au nouveau secret. Sinon, renouvelez pendant une période calme et surveillez vos journaux pour détecter les échecs de vérification juste après.

Remplacement du webhook au niveau du formulaire

Les demandes KYC créées via un formulaire peuvent remplacer l'URL de webhook par défaut de l'organisation par une URL propre au formulaire. Configurez cette option dans la page de paramètres du formulaire, dans le tableau de bord. Cela est utile lorsque plusieurs intégrations partagent le même compte Certivant : vous pouvez diriger chaque formulaire vers l'équipe qui en est responsable.

Le secret de signature est partagé entre l'URL par défaut et les remplacements par formulaire. L'en-tête de signature est identique, quelle que soit l'URL qui reçoit l'événement.

Ce qui ne déclenche pas de webhook

Certaines actions ne déclenchent pas de webhook :

• La création, la révocation ou la modification des portées d'une clé d'API.
• Les modifications de paramètres (modifications de la marque blanche, ajustements des seuils KYC).
• Les téléchargements de documents.
• Les commentaires de révision manuelle.

Si vous devez réagir à ces actions, consultez plutôt le Journal d'activité du tableau de bord : il n'existe pas encore d'API publique pour celui-ci.

Étapes suivantes

• Vérification de la signature — à faire avant la mise en production. Sans elle, n'importe qui peut forger des requêtes vers votre URL de webhook.
• Événements — le catalogue complet des types d'événements et des charges utiles.
• Nouvelles tentatives — ce qui se passe lorsque votre point de terminaison est indisponible.