Webhooks

Webhooks ermöglichen es Ihren Systemen, Echtzeit-Benachrichtigungen zu erhalten, wenn in Fynex Events auftreten. Statt die API zu pollen, sendet Fynex bei jedem abonnierten Event einen HTTP-POST an Ihre URL.

Webhook einrichten

1. Öffnen Sie Einstellungen > Integrationen.
2. Im Bereich Webhooks klicken Sie auf Webhook hinzufügen.
3. Tragen Sie die URL ein, an die Fynex Events senden soll (muss HTTPS sein).
4. Wählen Sie die Events, die Sie abonnieren möchten.
5. Klicken Sie auf Speichern. Fynex erzeugt ein Signing Secret für diesen Webhook — kopieren und sicher aufbewahren.

Verfügbare Events

Event	Ausgelöst, wenn
account.created	Ein neuer Account wird dem Portfolio hinzugefügt
account.updated	Account-Daten geändert werden (Saldo, Status, Metadaten)
account.status_changed	Account-Status wechselt (z. B. active → resolved)
contact.created	Ein neuer Kontakt wird einem Account hinzugefügt
contact.updated	Kontaktdaten werden geändert
interaction.completed	Eine Kommunikation (Call, E-Mail, SMS, WhatsApp) abgeschlossen ist
promise.created	Eine Zahlungszusage registriert wird
promise.fulfilled	Eine Zusage als erfüllt markiert wird (Zahlung eingegangen)
promise.broken	Eine Zusage überfällig ist ohne Zahlung
payment.registered	Eine Zahlung für einen Account erfasst wird
dispute.created	Ein Schuldner erhebt einen Dispute
escalation.created	Ein Account eskaliert wird (menschliche Prüfung, Legal, Supervisor)

Payload-Format

Jede Webhook-Anfrage ist ein JSON-POST mit folgender Struktur:

{
  "event_type": "promise.created",
  "timestamp": "2026-03-22T14:30:00.000Z",
  "data": {
    "id": "a1b2c3d4-...",
    "account_id": "e5f6g7h8-...",
    "amount": 15000,
    "due_date": "2026-04-05"
  }
}

Das Objekt data enthält die vollständige Ressource, die das Event ausgelöst hat. Die Form variiert je nach Event-Typ — z. B. enthält account.updated Account-Felder, interaction.completed Interaction-Details.

Signatur-Prüfung

Jede Webhook-Anfrage enthält den Header X-Fynex-Signature mit einer HMAC-SHA256-Signatur über den Request-Body. Prüfen Sie diese Signatur immer, um sicherzustellen, dass die Anfrage von Fynex stammt.

Prüfung in Node.js

const crypto = require("crypto");

function verifyWebhookSignature(rawBody, secret, signatureHeader) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return expected === signatureHeader;
}

// In Ihrem Webhook-Handler:
const isValid = verifyWebhookSignature(
  req.rawBody,
  process.env.FYNEX_WEBHOOK_SECRET,
  req.headers["x-fynex-signature"]
);

if (!isValid) {
  return res.status(401).send("Invalid signature");
}

WARNING

Prüfen Sie die Signatur immer, bevor Sie den Payload verarbeiten. Verwenden Sie in der Produktion einen zeitkonstanten Vergleich, um Timing-Angriffe zu erschweren.

Retry-Policy

Liefert Ihr Endpoint keinen 2xx-Status oder antwortet nicht innerhalb von 10 Sekunden, wiederholt Fynex den Versuch mit exponentiellem Backoff:

Versuch	Verzögerung nach Fehler
1	1 Minute
2	5 Minuten
3	30 Minuten
4	2 Stunden
5	12 Stunden

Nach 5 aufeinanderfolgenden Fehlern wird die Webhook-Subscription automatisch deaktiviert. Sie können sie unter Einstellungen > Integrationen wieder aktivieren, nachdem das Problem behoben ist.

Webhooks testen

Jeder Webhook-Endpoint hat in Einstellungen > Integrationen einen Button Test senden. Damit wird ein Beispiel-Event an Ihre URL gesendet, sodass Sie Erreichbarkeit und Signatur-Prüfung testen können, ohne auf ein echtes Event zu warten.

TIP

In der Entwicklung eignen sich Tools wie webhook.site oder ngrok, um einen lokalen Server öffentlich zu machen und eingehende Payloads zu inspizieren.

Fehlerbehebung

• Keine Events — Prüfen Sie, ob Ihre URL öffentlich per HTTPS erreichbar ist, schnell 200 liefert und der Webhook nicht deaktiviert ist.
• Signatur stimmt nicht — Vergleichen Sie gegen den rohen Request-Body (nicht geparstes JSON). Verwenden Sie das richtige Signing Secret für diesen Webhook.
• Webhook deaktiviert — Nach 5 Fehlversuchen deaktiviert Fynex die Subscription. Beheben Sie das Problem am Endpoint und aktivieren Sie den Webhook wieder unter Einstellungen.
• Doppelte Events — Nutzen Sie event_type und data.id zur Deduplizierung. Retries können dasselbe Event mehrfach zustellen.
• Langsame Verarbeitung — Antworten Sie sofort mit 200 und verarbeiten Sie den Payload asynchron. Fynex bricht nach 10 Sekunden ab.