Webhooks-Übersicht

Webhooks-Übersicht

Webhooks ermöglichen es Ihrer Anwendung, Echtzeit-HTTP-POST-Benachrichtigungen zu empfangen, wenn Ereignisse in Ihrer ZenFlip-Organisation auftreten. Anstatt die API nach Änderungen abzufragen, registrieren Sie eine URL und ZenFlip sendet Ereignis-Payloads automatisch dorthin.

Verfügbare Ereignisse

ZenFlip sendet Webhooks für folgende Ereignistypen:

Einen Webhook registrieren

Konfigurieren Sie Webhook-URLs im ZenFlip-Dashboard:

1. Navigieren Sie zu Einstellungen > Webhooks.

2. Klicken Sie auf Webhook-Endpunkt hinzufügen.

3. Geben Sie die URL ein, an die Sie Ereignisse empfangen möchten (muss HTTPS sein).

4. Wählen Sie die Ereignisse aus, die Sie abonnieren möchten (oder wählen Sie alle aus).

5. Klicken Sie auf Speichern.

ZenFlip generiert ein Signaturgeheimnis für jeden Webhook-Endpunkt. Kopieren und speichern Sie es sicher --- Sie benötigen es zur Verifizierung von Webhook-Signaturen.

Sie können mehrere Webhook-Endpunkte registrieren. Jeder Endpunkt kann verschiedene Ereignistypen abonnieren.

Payload-Format

Jede Webhook-Zustellung ist eine HTTP-POST-Anfrage mit einem JSON-Body. Die Payload-Struktur ist über alle Ereignistypen hinweg konsistent:

`json { "id": "wh_del_550e8400-e29b-41d4-a716-446655440000", "event": "publication.converted", "createdAt": "2026-02-20T14:05:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "versionNumber": 2, "status": "ready", "pageCount": 24 } } `

Felder der obersten Ebene

Anfrage-Header

Jede Webhook-Anfrage enthält die folgenden benutzerdefinierten Header:

Signaturverifizierung

Jede Webhook-Anfrage wird mit dem Signaturgeheimnis Ihres Endpunkts mittels HMAC-SHA256 signiert. Verifizieren Sie die Signatur immer, um zu bestätigen, dass die Anfrage von ZenFlip stammt und nicht manipuliert wurde.

Die Signatur wird über den rohen Anfragekörper berechnet:

` HMAC-SHA256(signing_secret, raw_request_body) `

Das Ergebnis wird als hexkodierter String im X-ZenFlip-Signature-Header gesendet.

Verifizierungsbeispiel (Node.js)

`javascript const crypto = require("crypto");

function verifyWebhookSignature(rawBody, signature, secret) { const expected = crypto .createHmac("sha256", secret) .update(rawBody, "utf8") .digest("hex");

// Timing-sichere Vergleichsfunktion zur Vermeidung von Timing-Angriffen verwenden return crypto.timingSafeEqual( Buffer.from(signature, "hex"), Buffer.from(expected, "hex") ); }

// In Ihrem Express-Route-Handler app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { const signature = req.headers["x-zenflip-signature"]; const secret = process.env.ZENFLIP_WEBHOOK_SECRET;

if (!verifyWebhookSignature(req.body, signature, secret)) { console.error("Invalid webhook signature"); return res.status(401).send("Invalid signature"); }

const event = JSON.parse(req.body); console.log("Received event:", event.event, event.id);

// Ereignis verarbeiten...

res.status(200).send("OK"); }); `

Wichtig: Verwenden Sie express.raw() (oder ein Äquivalent), um auf den rohen Anfragekörper für die Signaturverifizierung zuzugreifen. Das Parsen des Bodys als JSON und erneutes Stringifizieren kann eine andere Byte-Sequenz erzeugen, die nicht mit der Signatur übereinstimmt.

Wiederholungsrichtlinie

Wenn Ihr Endpunkt nicht innerhalb von 10 Sekunden mit einem 2xx-Statuscode antwortet, betrachtet ZenFlip die Zustellung als fehlgeschlagen und wiederholt mit exponentiellem Backoff:

Nach insgesamt 4 Versuchen (1 initial + 3 Wiederholungen) wird die Zustellung als failed markiert. Sie können den Zustellungsverlauf einsehen und fehlgeschlagene Zustellungen manuell über das Dashboard wiederholen.

Idempotenz

Jede Zustellung hat eine eindeutige id (die auch im X-ZenFlip-Delivery-Id-Header gesendet wird). Verwenden Sie diese ID zur Deduplizierung von Ereignissen, falls dieselbe Zustellung aufgrund von Wiederholungen oder Netzwerkproblemen mehr als einmal empfangen wird.

Antwortanforderungen

Ihr Webhook-Endpunkt muss:

1. Mit HTTP 2xx antworten (200, 201, 202, 204), um den Empfang zu bestätigen.

2. Innerhalb von 10 Sekunden antworten. Wenn Sie zeitaufwändige Verarbeitung durchführen müssen, bestätigen Sie den Webhook sofort und verarbeiten Sie ihn asynchron.

3. POST-Anfragen akzeptieren mit Content-Type: application/json.

`javascript // Empfohlenes Muster: sofort bestätigen, asynchron verarbeiten app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { // Zuerst Signatur verifizieren // ...

// Empfang sofort bestätigen res.status(200).send("OK");

// Asynchron verarbeiten const event = JSON.parse(req.body); processWebhookEvent(event).catch(console.error); }); `

Webhooks testen

Das ZenFlip-Dashboard enthält ein Webhook-Test-Tool:

1. Gehen Sie zu Einstellungen > Webhooks.

2. Klicken Sie auf die Schaltfläche Test neben Ihrem Endpunkt.

3. Wählen Sie einen Ereignistyp, um einen Beispiel-Payload zu senden.

4. Überprüfen Sie das Zustellungsprotokoll, um die Anfrage, Antwort und eventuelle Fehler zu sehen.

Sie können auch Tools wie ngrok verwenden, um einen lokalen Entwicklungsserver für Tests im Internet zugänglich zu machen:

`bash

ngrok starten, um eine öffentliche URL für Ihren lokalen Server zu erstellen

ngrok http 3000

Verwenden Sie die generierte URL (z.B. https://abc123.ngrok.io/webhooks/zenflip)

als Ihren Webhook-Endpunkt im ZenFlip-Dashboard

`

Zustellungsverlauf

Alle Webhook-Zustellungen werden protokolliert und sind über das Dashboard zugänglich. Jeder Eintrag zeigt:

• Ereignistyp und Zustellungs-ID

• Zeitstempel

• HTTP-Antwortstatus von Ihrem Endpunkt

• Antwortkörper (erste 1.000 Zeichen)

• Anzahl der Versuche

• Aktueller Status: pending, success oder failed

Nächste Schritte

• [Webhook-Ereignis-Referenz](/docs/webhooks-events) --- Detaillierte Payload-Schemas für jeden Ereignistyp mit Beispiel-JSON.