Warum Webhooks verwenden?
ChannelDock stellt Webhooks bereit, um Ihr System sofort zu informieren, wenn sich in Ihrem Konto etwas ändert. Statt die API periodisch abzufragen, erhalten Sie automatisch eine Benachrichtigung, wenn eine Bestellung erstellt oder aktualisiert wird, eine Sendung angelegt wird, Lagerbestände sich ändern oder eine Rücksendung registriert wird. Webhooks helfen Ihnen, Prozesse zu automatisieren und unnötige API-Anfragen zu reduzieren.
Hauptfunktionen
Ereigniszeitpunkt: Webhooks werden einige Minuten nach Eintritt eines Ereignisses ausgelöst und liefern Ihnen nahezu Echtzeit-Updates.
Konsistenz der Nutzlast: Die JSON-Nutzlast eines Webhooks entspricht der Struktur, die vom entsprechenden API-Endpunkt zurückgegeben wird.
Automatische Wiederholungen: Wenn ChannelDock einen Webhook nicht zustellen kann, werden bis zu fünf Versuche mit zunehmenden Verzögerungen (0, 30, 60, 120 und 240 Sekunden) unternommen. Nach zehn fehlgeschlagenen Zustellversuchen wird der Webhook aus Sicherheitsgründen deaktiviert.
Sicherheit: Jeder Webhook kann einen eigenen geheimen Schlüssel haben. ChannelDock verwendet diesen geheimen Schlüssel, um eine digitale Signatur zu berechnen, damit Sie die Authentizität der Nutzlast überprüfen können.
Einrichten eines Webhooks
Zu den Einstellungen navigieren: Melden Sie sich bei ChannelDock an und gehen Sie zu Einstellungen → API & Webhooks. Sie sehen zwei Bereiche: API-Schlüssel und Webhooks.
Neuen Webhook erstellen: Klicken Sie auf Neuen Webhook erstellen. Es erscheint ein Fenster „Webhook-Konfiguration“.
Felder ausfüllen:
Name des Webhooks: Wählen Sie einen aussagekräftigen internen Namen (zum Beispiel „Bestell-Updates“).
Webhook-URL: Geben Sie die URL Ihres Endpunkts ein, an die ChannelDock eine HTTP-POST-Anfrage senden kann. Stellen Sie sicher, dass diese URL öffentlich erreichbar ist und innerhalb von 5 Sekunden antwortet.
Auslösendes Ereignis: Wählen Sie den Ereignistyp, über den Sie Benachrichtigungen erhalten möchten. Mögliche Ereignisse sind
order.created,order.updated,order.status.changed,order.deleted,shipment.created,stock.updated,return.created,return.handledundreturn.product.updated.Status: Lassen Sie dies auf Aktiv. Webhooks werden nach 10 fehlgeschlagenen Zustellversuchen automatisch deaktiviert.
Webhook-Geheimnis (optional, aber empfohlen): Geben Sie ein eigenes Geheimnis an oder klicken Sie auf Generieren, um ein starkes Geheimnis zu erstellen. ChannelDock verwendet dieses Geheimnis, um eine HMAC‑SHA256-Hash-Signatur zu berechnen, damit Sie die Nutzlast überprüfen können.
Speichern: Klicken Sie auf Webhook speichern. ChannelDock speichert Ihren Webhook und sendet Ereignisse des von Ihnen ausgewählten Typs an Ihren Endpunkt.
Aufbau der Nutzlast und Ereignisse
Wenn ein ausgewähltes Ereignis eintritt, sendet ChannelDock eine JSON-Nutzlast an Ihren Endpunkt. Die Nutzlast enthält mindestens die folgenden Felder:
{
"event": "order.created",
"payload": {
...
},
"signature": "<hash>" (Optional but recommended)
}
event – das Ereignis, für das der Webhook konfiguriert wurde (zum Beispiel
order.created).payload – enthält Details zur Bestellung, Sendung, Rücksendung oder Lageränderung. Die Struktur entspricht der API-Antwort für das entsprechende Objekt.
signature – ist nur vorhanden, wenn ein Geheimnis konfiguriert wurde. Dabei handelt es sich um eine HMAC‑SHA256-Signatur der gesamten Nutzlast, mit Ausnahme des Feldes signature selbst.
Überprüfen der Signatur
Es ist wichtig sicherzustellen, dass der Webhook von ChannelDock gesendet wurde und die Nutzlast nicht manipuliert wurde. Dazu vergleichen Sie die von ChannelDock bereitgestellte Signatur mit Ihrer eigenen Berechnung.
Intern verwendet ChannelDock für jede Nutzlast eine Signatur, indem ein HMAC‑SHA256-Hash der JSON-Daten mit dem von Ihnen konfigurierten Geheimnis berechnet wird. Der resultierende Hash wird als Feld signature in die Nutzlast eingefügt.
Signatur in Ihrer Anwendung überprüfen
Webhook empfangen: Parsen Sie das JSON und speichern Sie vorübergehend den Wert des Feldes
signature. Entfernen Sie das Feldsignatureaus der Nutzlast, bevor Sie den Hash berechnen.Hash erzeugen: Verwenden Sie Ihren geheimen Schlüssel zusammen mit der HMAC-SHA256-Hashmethode, um eine neue Signatur zu erstellen. Führen Sie dies auf den empfangenen JSON-Daten aus (ohne das Feld
signature).Hashes vergleichen: Stimmen der von Ihnen berechnete Hash und die empfangene Signatur exakt überein, können Sie darauf vertrauen, dass die Nutzlast authentisch und unverändert ist.
Tipps für sichere Verarbeitung
Weisen Sie jedem Webhook ein eigenes Geheimnis zu und wechseln Sie dieses regelmäßig.
Verwenden Sie eine Vergleichsfunktion mit konstanter Laufzeit (zum Beispiel
hash_equalsin PHP), um Timing‑Angriffe zu verhindern.Führen Sie zusätzliche Prüfungen des Inhalts der Nutzlast durch (zum Beispiel die Überprüfung, dass die Bestellung existiert), bevor Sie Aktionen ausführen.
Bewährte Vorgehensweisen
ChannelDock empfiehlt folgende Vorgehensweisen, um Webhooks sicher und zuverlässig zu verarbeiten:
HTTP‑200-Antwort: Lassen Sie Ihren Endpunkt ein HTTP 200 OK zurückgeben, sobald die Nutzlast erfolgreich empfangen wurde. Andernfalls betrachtet ChannelDock den Versuch als fehlgeschlagen und versucht es erneut.
Idempotenz: Webhook-Nachrichten können manchmal doppelt gesendet werden (zum Beispiel aufgrund von Netzwerkproblemen oder Wiederholungsversuchen). Stellen Sie sicher, dass Ihre Verarbeitungslogik idempotent ist, damit doppelte Nachrichten nicht zu doppelter Arbeit führen.
Überwachung: Verwenden Sie das ChannelDock-Dashboard, um den Status Ihrer Webhooks zu überwachen und Fehler zu identifizieren.
Umgang mit Nutzlasten: Stellen Sie sicher, dass Ihr Endpunkt große Nutzlasten verarbeiten kann und innerhalb einer vernünftigen Zeit (≤ 5 Sekunden) antwortet. Webhooks werden nach zehn fehlgeschlagenen Zustellversuchen automatisch deaktiviert.
Dieser Artikel wurde automatisch aus dem Englischen übersetzt.