Tentativi e consegna

Certivant è progettato per consegnare ogni evento almeno una volta. Se il Suo endpoint è brevemente non disponibile — un deploy, un problema del database, un'interruzione di 30 secondi — i tentativi fanno in modo che l'evento arrivi comunque. Questa pagina spiega il comportamento esatto, così può pianificare di conseguenza.

Il criterio dei tentativi in sintesi

Dopo il quinto tentativo fallito, l'evento viene contrassegnato come esaurito. Non viene più riprovato automaticamente. Viene inviata un'email al proprietario dell'organizzazione per avvisarlo che i webhook stanno fallendo.

La sequenza temporale

gantt
  title Webhook delivery attempts
  dateFormat X
  axisFormat %s
  section Attempts
  Attempt 1 (immediate) :a1, 0, 1s
  Attempt 2 (+5s)       :a2, 5, 1s
  Attempt 3 (+30s)      :a3, 35, 1s
  Attempt 4 (+5min)     :a4, 335, 1s
  Attempt 5 (+1h)       :a5, 3935, 1s
  Attempt 6 (+24h)      :a6, 90335, 1s

Il conteggio parte quando l'evento viene generato. Se il Suo endpoint è funzionante al primo tentativo, non vedrà mai nuovi tentativi. Se resta non disponibile per tutte le circa 25 ore, l'evento si esaurisce.

Che cosa conta come successo

Certivant considera il Suo endpoint funzionante quando:

• Lo stato HTTP è 2xx (200, 201, 204, ecc.).
• La risposta arriva entro 10 secondi dall'invio della richiesta.

Qualsiasi altra risposta è un fallimento di consegna:

• Redirect 3xx — Certivant non segue i redirect. Punti l'URL del webhook alla destinazione finale.
• 4xx (inclusi 401 e 404) — Certivant riprova comunque, nel caso il problema sia transitorio (controllo di autenticazione al primo avvio, route non ancora distribuita). La maggior parte delle integrazioni vuole indagare su qualsiasi 4xx: di solito indica una configurazione errata dalla Sua parte.
• 5xx — errore del server. Riprova standard.
• Connessione rifiutata, errore DNS, errore di handshake TLS — stesso comportamento di nuovo tentativo.
• Nessuna risposta entro 10 secondi — Certivant interrompe la richiesta e la conta come fallimento. Il nuovo tentativo prosegue.

Progettare un gestore rapido

Ha un budget di 10 secondi. Faccia in modo sincrono solo il minimo indispensabile:

app.post("/webhooks/certivant", async (c) => {
  const rawBody = await c.req.text();

  // 1. Verify signature
  if (!verifyCertivantSignature(rawBody, c.req.header("X-Certivant-Signature-V2"), SECRET)) {
    return c.json({ error: "Invalid signature" }, 401);
  }

  // 2. Persist to queue (single DB write, fast)
  const eventId = c.req.header("X-Certivant-Event-Id")!;
  await db.webhookEventQueue.create({
    data: { id: eventId, payload: rawBody },
  });

  // 3. Acknowledge immediately
  return c.json({ received: true }, 200);
});

// Process the queue asynchronously
async function workerLoop() {
  while (true) {
    const event = await db.webhookEventQueue.findFirst({ where: { processedAt: null } });
    if (!event) { await sleep(1000); continue; }
    try {
      await handleEvent(JSON.parse(event.payload));
      await db.webhookEventQueue.update({ where: { id: event.id }, data: { processedAt: new Date() } });
    } catch (err) {
      // Bounded retry on your side; surface after N attempts
    }
  }
}

Questo schema separa la conferma di ricezione (che deve essere rapida) dalla logica di business (che può essere lenta o riprovata in modo indipendente). I Suoi servizi a valle (invio di email di benvenuto, creazione di account, ecc.) possono fallire senza far riprovare Certivant.

Quando il Suo endpoint è davvero non disponibile

Se resterà non disponibile per un periodo prolungato (manutenzione, migrazione), i nuovi tentativi la copriranno per circa 25 ore. Oltre:

• Gli eventi esauriti restano consultabili tramite GET /api/v1/kyc/requests/:id — lo stato attuale è sempre disponibile sulla richiesta stessa. Scorra le richieste create durante l'indisponibilità e sincronizzi lo stato manualmente.
• Il proprietario dell'organizzazione riceve un'email quando un evento si esaurisce. L'email include l'ID della richiesta, così è facile da cercare.
• Lo stato di consegna dei webhook (consegnato / fallito / esaurito), il numero di tentativi, l'ultimo codice di risposta e il prossimo nuovo tentativo programmato sono visibili nella dashboard in KYC → Impostazioni → Webhook → Registro delle consegne, dove ogni evento fallito o esaurito ha un pulsante Riprova ora (e un nuovo tentativo in blocco).

Ritrasmettere un evento esaurito

Dal registro delle consegne, Riprova ora rinvia immediatamente un evento fallito o esaurito, firmato con il segreto attuale, e riavvia il suo contatore dei tentativi. Non esiste un endpoint pubblico (con chiave API) per riattivare un singolo evento. Altre opzioni:

1. Recuperi lo stato tramite l'API. GET /api/v1/kyc/requests/:id restituisce sempre lo stato attuale, inclusa la decisione finale. È la risposta giusta per recuperare il ritardo dopo un'interruzione.
2. Chieda al supporto di riprodurre se le manca un grosso lotto. Includa gli ID delle richieste o la finestra temporale: il supporto può riemettere gli eventi per Lei.

Interazione con il limite di frequenza

La consegna dei webhook non viene conteggiata nel limite di frequenza della Sua chiave API — sono sistemi separati. Può ricevere centinaia di webhook al minuto e contemporaneamente effettuare centinaia di chiamate API al minuto con la stessa chiave, e nessuno dei due budget influisce sull'altro.

Idempotenza, riesaminata

Poiché esistono i nuovi tentativi, lo stesso evento logico arriverà talvolta due volte. Vedi Eventi → Idempotenza per lo schema di deduplicazione consigliato, che usa X-KYC-Event-Id.

Suggerimenti per il monitoraggio

Un'integrazione webhook sana ha:

• Un tempo di risposta mediano dell'endpoint del webhook sotto i 500 ms. Se sale, rischia di raggiungere il timeout di 10 secondi sotto carico.
• Zero 4xx e 5xx dall'URL del webhook in funzionamento normale. Imposti un avviso per entrambi.
• Una tabella di log di idempotenza che può interrogare per confermare che ogni webhook sia stato elaborato almeno una volta.

Se riceve email di eventi esauriti, le cause radice più comuni sono: (a) l'URL del webhook è sbagliato (refuso nella dashboard), (b) il Suo endpoint richiede un'autenticazione che Certivant non fornisce (l'URL deve accettare POST non autenticati — l'intestazione della firma è l'autenticazione), (c) il Suo endpoint è costantemente più lento di 10 secondi. Indaghi su ciascuna.