Configurazione dei webhook

I webhook permettono a Certivant di inviare al Suo backend i cambiamenti di stato in tempo reale. Invece di interrogare GET /requests/:id finché l'elaborazione non termina, Certivant invia una POST a un URL di Sua proprietà ogni volta che si verifica un evento di interesse.

Questa pagina riguarda la configurazione una tantum. Per la verifica della firma che deve implementare prima di andare in produzione, vedi Verifica della firma.

Che cosa Le servirà

• Un URL HTTPS raggiungibile pubblicamente che accetta richieste POST con un corpo JSON. In sviluppo va bene anche localhost, se usa un tunnel (ngrok, Cloudflare Tunnel, tailscale funnel).
• Il ruolo Proprietario o Amministratore sull'organizzazione Certivant — i membri non possono modificare le impostazioni dei webhook.
• Un modo per conservare i segreti — riceverà un segreto di firma HMAC che deve custodire insieme alle altre credenziali di produzione.

1 — Costruisca il Suo endpoint

Un gestore minimo ha questo aspetto (mostrato con Node e Hono; qualsiasi framework va bene):

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);
});

Le due regole non negoziabili:

1. Risponda con 2xx entro 10 secondi. Certivant considera qualsiasi altra risposta (5xx, 4xx, timeout, errore di connessione) un fallimento di consegna e riprova con backoff esponenziale.
2. Legga il corpo grezzo prima di analizzare il JSON. La verifica della firma calcola l'hash della stringa di byte esatta inviata da Certivant. Se il framework analizza prima il JSON, rigenererà una stringa diversa e la firma non corrisponderà.

2 — Configuri l'URL nella dashboard

3 — Invii un evento di prova

Due pulsanti La aiutano a verificare l'integrazione:

• Test (accanto all'URL del webhook) invia un leggero ping di connettività kyc.webhook.test con test: true. Conferma solo che il Suo endpoint è raggiungibile e restituisce 2xx — non richiede dati di richiesta e funziona anche prima di aver salvato un segreto di firma. Lo riconosca subito (vedi il gestore sopra).

• Invia un evento di prova (KYC → Sviluppatore → Eventi webhook) le permette di scegliere l'evento — il ping kyc.webhook.test oppure un payload di esempio kyc.request.created / approved / rejected / escalated — e lo invia con una POST firmato esattamente come una consegna reale (X-Certivant-Signature-V2 più le intestazioni X-KYC-*, timestamp Unix, il Suo segreto webhook). I payload di esempio contengono "test": true e un requestId fittizio. Lo usi per:

  • Confermare che l'URL sia raggiungibile dall'infrastruttura di Certivant.
  • Confermare che la verifica della firma accetti una firma valida.
  • Vedere la forma esatta del payload prima che si attivino eventi reali.

Può anche attivare un test in modo programmatico — utile quando vuole automatizzare i test di integrazione:

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

Il corpo è facoltativo (predefinito kyc.webhook.test). L'endpoint richiede un cookie di sessione, non una chiave API — è un'azione lato dashboard.

4 — Ruoti il segreto di firma

Quando un segreto viene esposto (oppure ogni anno, come buona prassi):

Non c'è una finestra di sovrapposizione lato mittente: le nuove consegne vengono firmate solo con il nuovo segreto. Le ricette di verifica in Verifica della firma accettano un elenco di segreti e più valori v1=, quindi può distribuire un verificatore che accetta sia il vecchio sia il nuovo segreto prima di ruotare. In alternativa, ruoti durante un periodo tranquillo e controlli i log subito dopo per eventuali errori di verifica.

Sostituzione del webhook per modulo

Le richieste KYC create tramite un modulo possono sostituire l'URL webhook predefinito dell'organizzazione con un URL specifico per modulo. Lo configuri nella pagina delle impostazioni del modulo nella dashboard. È utile quando ha più integrazioni che condividono lo stesso account Certivant — indirizzi ogni modulo al team che ne è responsabile.

Il segreto di firma è condiviso tra l'URL predefinito e le sostituzioni per modulo. L'intestazione della firma è identica, indipendentemente dall'URL che riceve l'evento.

Ciò che non genera webhook

Alcune operazioni non attivano webhook:

• Creazione, revoca o modifica degli ambiti di una chiave API.
• Modifiche alle impostazioni (modifiche al white-label, ritocchi alle soglie KYC).
• Download di documenti.
• Commenti di revisione manuale.

Se deve reagire a questi eventi, consulti invece il Registro attività della dashboard — non esiste ancora un'API pubblica per esso.

Passi successivi

• Verifica della firma — lo faccia prima della produzione. Senza di essa, chiunque può falsificare richieste verso il Suo URL webhook.
• Eventi — il catalogo completo dei tipi di evento e dei payload.
• Nuovi tentativi — cosa succede quando il Suo endpoint non è disponibile.