DataFirefly Webhooks — Vollständige Anleitung

Überblick

DataFirefly Webhooks verbindet Ihren PrestaShop-8- und -9-Shop mit über 5000 Apps, in beide Richtungen. Ausgehend sendet Ihr Shop seine Ereignisse (Bestellungen, Kunden, Bestand…) an Zapier, Make, n8n oder jeden HTTP-Endpunkt. Eingehend können dieselben Tools über eine gesicherte API Daten in den Shop schreiben.

Das Modul stützt sich auf drei Säulen: eine asynchrone Warteschlange (keine Bestellung wird ausgebremst), automatische Wiederholungen mit exponentiellem Backoff und eine HMAC-SHA256-Signatur, die die Echtheit der Nachrichten garantiert.

Installation

1. Laden Sie das Archiv dfwebhooks.zip aus Ihrem DataFirefly-Konto herunter.
2. Gehen Sie im Back Office zu Module > Modulmanager > Modul hochladen und legen Sie das ZIP ab.
3. Klicken Sie auf Installieren und dann auf Konfigurieren.
4. Sie landen auf dem Hauptbildschirm, der die URL des Cron-Workers und die URL der eingehenden API anzeigt.

1. Den Cron-Worker planen (ausgehender Fluss)

Ausgehende Webhooks werden nicht sofort gesendet: Sie werden in eine Warteschlange gestellt und von einem Worker zugestellt, den Sie regelmäßig auslösen. Kopieren Sie die im Konfigurationsbildschirm angezeigte Cron-URL und planen Sie sie alle 1 bis 5 Minuten.

*/2 * * * * curl -s "https://ihr-shop.de/index.php?fc=module&module=dfwebhooks&controller=cron&token=IHR_TOKEN" >/dev/null 2>&1

Bei jedem Durchlauf verarbeitet der Worker bis zu 50 ausstehende Zustellungen, führt die nötigen Wiederholungen aus und bereinigt alte Protokolle gemäß der konfigurierten Aufbewahrung.

2. Einen ausgehenden Endpunkt erstellen

Ein Endpunkt verbindet ein Ereignis mit einer Ziel-URL. Klicken Sie im Hauptbildschirm auf Hinzufügen und füllen Sie aus:

• Name: eine interne Bezeichnung (z. B. „Neue Bestellung → Zapier“).
• Ereignis: das auslösende Ereignis (siehe Liste unten).
• URL: fügen Sie die „Catch Hook“-URL von Zapier oder „Custom Webhook“ von Make ein.
• Signaturgeheimnis (optional): wenn gesetzt, wird jeder Payload mit HMAC-SHA256 signiert.

Bedingte Filter

Sie können einen Webhook nur senden, wenn bestimmte Bedingungen erfüllt sind. Die Regeln liegen als JSON vor und werden mit logischem UND verknüpft. Verfügbare Operatoren: eq, neq, gt, gte, lt, lte, in, contains.

[{"field":"order.total_paid","op":"gte","value":100}]

Dieses Beispiel löst den Webhook nur für Bestellungen aus, deren bezahlter Gesamtbetrag größer oder gleich 100 ist.

Feld-Mapping

Standardmäßig wird der vollständige Payload gesendet. Um nur bestimmte Felder in einer präzisen Form zu senden, definieren Sie ein Mapping: Der Schlüssel ist der Ausgabename, der Wert der Pfad im Payload.

{"email":"customer.email","total":"order.total_paid"}

3. Verfügbare ausgehende Ereignisse

• order.created — eine Bestellung wurde gerade bestätigt.
• order.status.updated — der Status einer Bestellung ändert sich.
• order.refunded — eine Bestellung wechselt in den Status erstattet.
• customer.created — ein neuer Kunde registriert sich.
• address.created — eine neue Adresse wird erstellt.
• product.created — ein Produkt wird hinzugefügt.
• product.updated — ein Produkt wird geändert.
• product.stock.low — der Bestand fällt unter den konfigurierten Schwellenwert.
• review.created — eine Bewertung wird freigegeben (erfordert ein kompatibles Bewertungsmodul).

4. Eingehende API (Zapier/Make/n8n → PrestaShop)

Die eingehende API erlaubt es Ihren Automatisierungen, den Shop zu verändern. Sie ist durch ein Token und optional durch eine HMAC-Signatur geschützt.

Ein Token erstellen

Geben Sie im Panel Eingehende Tokens eine Bezeichnung an, wählen Sie die erlaubten Scopes (orders, products, customers) und bei Bedarf ein Signaturgeheimnis. Das erzeugte Token fügen Sie in Ihr Tool ein.

Eine Anfrage senden

Senden Sie ein POST an die URL der eingehenden API. Das Token kommt in den Header X-DF-Token (oder als Parameter ?token=). Der Body ist ein JSON mit einer action und einem data-Objekt.

POST https://ihr-shop.de/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: IHR_TOKEN
Content-Type: application/json

{"action":"order.status.update","data":{"id_order":42,"id_order_state":4}}

5. Verfügbare eingehende Aktionen

• order.status.update (Scope orders) — ändert den Status einer Bestellung. Felder: id_order, id_order_state, send_email (optional).
• order.get (Scope orders) — ruft eine Bestellung ab. Feld: id_order.
• product.stock.update (Scope products) — setzt den Bestand. Felder: id_product, quantity, id_product_attribute (optional).
• product.upsert (Scope products) — erstellt oder aktualisiert ein Produkt anhand seiner reference.
• customer.upsert (Scope customers) — erstellt oder aktualisiert einen Kunden anhand seiner email.
• customer.get (Scope customers) — ruft einen Kunden anhand von email oder id_customer ab.

6. Die HMAC-Signatur prüfen

Wenn ein Geheimnis am Endpunkt (ausgehend) oder am Token (eingehend) konfiguriert ist, trägt die Nachricht einen Header X-DF-Signature: sha256=.... Um sie beim Empfang zu prüfen, berechnen Sie den HMAC des Rohkörpers mit Ihrem Geheimnis neu und vergleichen in konstanter Zeit.

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
if (hash_equals($expected, $signatureHeader)) {
    // gültige Signatur
}

Berechnen Sie den HMAC immer über den Rohkörper (nicht neu serialisiert), sonst stimmt die Signatur nicht überein.

7. Zustellprotokoll und erneutes Senden

Das Menü Webhooks Delivery Log listet jeden Versuch mit seinem Status:

• SENT — zugestellt mit einem HTTP-2xx-Code.
• PENDING — in der Warteschlange, wartet auf den nächsten Worker-Durchlauf.
• FAILED — vorübergehender Fehler, eine Wiederholung ist geplant.
• DEAD — endgültiger Fehler nach 6 Versuchen.

Wiederholungen folgen einem exponentiellen Backoff: 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, dann 6 Stunden. Sie können jederzeit über die Schaltfläche Replay ein erneutes Senden erzwingen und den exakten Payload über die Aktion Ansehen einsehen.

8. Multishop, DSGVO und Batch-Modus

Jeder Endpunkt und jedes Token ist einem bestimmten Shop zugeordnet: Die Flüsse eines Shops gelangen nie in einen anderen. Die Option Personenbezogene Daten anonymisieren maskiert E-Mails, Telefonnummern und Namen vor dem Versand, um DSGVO-konform zu bleiben, wenn das Ziel keine identifizierenden Daten erhalten soll. Der Batch-Modus bündelt die Sendungen für hohe Volumen.

FAQ und Fehlerbehebung

Es wird kein Webhook gesendet. Prüfen Sie, ob der Cron-Worker geplant ist und seine URL (mit dem richtigen Token) antwortet. Sehen Sie ins Protokoll: Wenn Zeilen auf PENDING bleiben, läuft der Cron nicht.

Der entfernte Endpunkt gibt einen Fehler 401/403 zurück. Ihr Tool erwartet möglicherweise eine Signaturprüfung: Setzen Sie auf beiden Seiten dasselbe Geheimnis oder entfernen Sie es während der Tests.

Die eingehende API gibt „insufficient_scope“ zurück. Dem verwendeten Token fehlt der von der Aktion geforderte Scope. Bearbeiten Sie das Token, um den passenden Scope (orders, products oder customers) zu aktivieren.

Die Test-Schaltfläche zeigt einen Fehler. Die Schaltfläche Test sendet synchron einen Beispiel-Payload: Ein Fehler bedeutet meist eine nicht erreichbare URL oder ein ungültiges TLS-Zertifikat auf der Zielseite.