Wiederholungen und Zustellung

Certivant ist so ausgelegt, dass jedes Ereignis mindestens einmal zugestellt wird. Wenn Ihr Endpunkt kurzzeitig nicht verfügbar ist — ein Deployment, ein Hänger der Datenbank, ein 30-sekündiger Ausfall —, stellen Wiederholungen sicher, dass das Ereignis trotzdem ankommt. Diese Seite erklärt das genaue Verhalten, damit Sie entsprechend planen können.

Die Wiederholungsrichtlinie auf einen Blick

Nach dem fünften fehlgeschlagenen Versuch wird das Ereignis als erschöpft markiert. Es wird nicht automatisch erneut versucht. An den Inhaber der Organisation wird eine E-Mail gesendet, die ihn darüber informiert, dass Webhooks fehlschlagen.

Der zeitliche Ablauf

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

Die Zeitmessung beginnt, sobald das Ereignis erzeugt wird. Wenn Ihr Endpunkt beim ersten Versuch funktioniert, sehen Sie nie eine Wiederholung. Ist er die vollen rund 25 Stunden nicht erreichbar, erschöpft sich das Ereignis.

Was als Erfolg gilt

Certivant betrachtet Ihren Endpunkt als funktionsfähig, wenn:

• der HTTP-Status 2xx ist (200, 201, 204 usw.).
• die Antwort innerhalb von 10 Sekunden nach dem Senden der Anfrage eintrifft.

Alles andere ist ein Zustellfehler:

• 3xx-Weiterleitungen — Certivant folgt Weiterleitungen nicht. Richten Sie die Webhook-URL direkt auf das endgültige Ziel.
• 4xx (einschließlich 401 und 404) — Certivant wiederholt trotzdem, falls das Problem vorübergehend ist (Authentifizierungsprüfung beim Kaltstart, Route noch nicht deployt). Die meisten Integrationen sollten jeden 4xx-Fehler untersuchen — er weist in der Regel auf eine Fehlkonfiguration auf Ihrer Seite hin.
• 5xx — Serverfehler. Übliche Wiederholung.
• Verbindung abgelehnt, DNS-Fehler, TLS-Handshake-Fehler — gleiches Wiederholungsverhalten.
• Keine Antwort innerhalb von 10 Sekunden — Certivant bricht die Anfrage ab und zählt sie als Fehler. Die Wiederholung läuft weiter.

Einen schnellen Handler entwerfen

Sie haben ein Budget von 10 Sekunden. Erledigen Sie synchron nur das absolut Notwendige:

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

Dieses Muster entkoppelt die Bestätigung (muss schnell sein) von der Geschäftslogik (darf langsam sein und kann unabhängig wiederholt werden). Ihre nachgelagerten Dienste (Willkommens-E-Mails senden, Konten bereitstellen usw.) dürfen fehlschlagen, ohne dass Certivant eine Wiederholung auslöst.

Wenn Ihr Endpunkt tatsächlich nicht erreichbar ist

Wenn Sie für einen längeren Zeitraum nicht erreichbar sein werden (Wartung, Migration), decken die Wiederholungen Sie trotzdem für rund 25 Stunden ab. Darüber hinaus gilt:

• Erschöpfte Ereignisse sind weiterhin über GET /api/v1/kyc/requests/:id abrufbar — der aktuelle Status steht immer an der Anfrage selbst. Gehen Sie die während Ihres Ausfalls erstellten Anfragen durch und synchronisieren Sie den Status manuell.
• Der Inhaber der Organisation erhält eine E-Mail, sobald ein Ereignis erschöpft ist. Die E-Mail enthält die Anfrage-ID, damit Sie sie leicht nachschlagen können.
• Der Status der Webhook-Zustellung (zugestellt / fehlgeschlagen / erschöpft), die Anzahl der Versuche, der letzte Antwortcode und die nächste geplante Wiederholung sind im Dashboard unter KYC → Einstellungen → Webhooks → Zustellprotokoll sichtbar. Dort hat jedes fehlgeschlagene oder erschöpfte Ereignis eine Schaltfläche Jetzt wiederholen (sowie eine Sammelwiederholung).

Ein erschöpftes Ereignis erneut zustellen

Im Zustellprotokoll sendet Jetzt wiederholen ein fehlgeschlagenes oder erschöpftes Ereignis sofort erneut, signiert mit dem aktuellen Geheimnis, und setzt seinen Versuchszähler zurück. Es gibt keinen öffentlichen Endpunkt (mit API-Schlüssel), um ein einzelnes Ereignis erneut auszulösen. Weitere Möglichkeiten:

1. Status über die API abrufen. GET /api/v1/kyc/requests/:id liefert immer den aktuellen Status einschließlich der endgültigen Entscheidung. Das ist die richtige Lösung, um nach einem Ausfall aufzuholen.
2. Den Support um eine erneute Zustellung bitten, wenn Ihnen eine große Charge fehlt. Geben Sie die Anfrage-IDs oder das Zeitfenster an — der Support kann Ereignisse für Sie erneut senden.

Wechselwirkung mit dem Ratenlimit

Die Webhook-Zustellung wird nicht auf Ihr API-Ratenlimit angerechnet — es handelt sich um getrennte Systeme. Sie können Hunderte Webhooks pro Minute empfangen und gleichzeitig Hunderte API-Aufrufe pro Minute mit demselben Schlüssel tätigen; keines der beiden Budgets beeinflusst das andere.

Idempotenz, erneut betrachtet

Da es Wiederholungen gibt, kommt dasselbe logische Ereignis manchmal zweimal an. Das empfohlene Muster zur Deduplizierung mit X-KYC-Event-Id finden Sie unter Ereignisse → Idempotenz.

Überwachungsempfehlungen

Eine gesunde Webhook-Integration hat:

• Eine mediane Antwortzeit des Webhook-Endpunkts unter 500 ms. Steigt sie, riskieren Sie unter Last das 10-Sekunden-Zeitlimit.
• Im Normalbetrieb keine 4xx- und 5xx-Antworten von der Webhook-URL. Richten Sie für beides einen Alarm ein.
• Eine Tabelle für das Idempotenz-Protokoll, die Sie abfragen können, um zu bestätigen, dass jeder Webhook mindestens einmal verarbeitet wurde.

Wenn Sie E-Mails über erschöpfte Ereignisse erhalten, sind die häufigsten Ursachen: (a) die Webhook-URL ist falsch (Tippfehler im Dashboard), (b) Ihr Endpunkt verlangt eine Authentifizierung, die Certivant nicht bereitstellt (die URL muss nicht authentifizierte POST-Anfragen annehmen — der Signatur-Header ist die Authentifizierung), (c) Ihr Endpunkt antwortet dauerhaft langsamer als 10 Sekunden. Untersuchen Sie jede dieser Ursachen.