Warum Webhooks verwenden?
ChannelDock stellt Webhooks bereit, um Ihr System sofort zu informieren, wenn sich etwas in Ihrem Konto ändert. Anstatt die API in regelmäßigen Abständen abzufragen, erhalten Sie automatisch eine Benachrichtigung, wenn eine Bestellung erstellt oder aktualisiert wird, eine Sendung erstellt wird, Lagerbestände sich ändern oder eine Rücksendung registriert wird. Webhooks helfen Ihnen, Prozesse zu automatisieren und unnötige API-Anfragen zu reduzieren.
Hauptmerkmale
Zeitpunkt des Ereignisses: Webhooks werden einige Minuten nach dem Eintreten eines Ereignisses ausgelöst und liefern so nahezu Echtzeit-Updates.
Konsistenz der Nutzlast: Die JSON-Nutzlast eines Webhooks entspricht der Struktur, die vom entsprechenden API-Endpunkt zurückgegeben wird.
Automatische Wiederholversuche: 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 seinen eigenen geheimen Schlüssel haben. ChannelDock verwendet diesen Schlüssel, um eine digitale Signatur zu berechnen, mit der 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.
Erstellen Sie einen neuen Webhook: Klicken Sie auf Neuen Webhook erstellen. Es erscheint ein Fenster „Webhook-Konfiguration“.
Füllen Sie die Felder aus:
Webhook name: Wählen Sie einen aussagekräftigen internen Namen (zum Beispiel „Bestellaktualisierungen“).
Webhook URL: Geben Sie die URL Ihres Endpunkts ein, an den ChannelDock eine HTTP-POST-Anfrage senden kann. Stellen Sie sicher, dass diese URL öffentlich erreichbar ist und innerhalb von 5 Sekunden antwortet.
Event to trigger webhook: Wählen Sie die Art des Ereignisses, über das Sie benachrichtigt werden 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 gesetzt. Webhooks werden nach 10 fehlgeschlagenen Zustellversuchen automatisch deaktiviert.
Webhook secret (optional but recommended): Geben Sie Ihr eigenes Secret ein oder klicken Sie auf Generieren, um ein starkes Secret zu erstellen. ChannelDock verwendet dieses Secret, um eine HMAC‑SHA256-Hash-Signatur zu berechnen, mit der Sie die Nutzlast verifizieren können.
Speichern: Klicken Sie auf Webhook speichern. ChannelDock speichert Ihren Webhook und sendet Ereignisse des ausgewählten Typs an Ihren Endpunkt.
Struktur der Nutzlast und Ereignisse
Wenn das gewählte 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, aber empfohlen)
}
event – das Ereignis, für das der Webhook konfiguriert wurde (zum Beispiel
order.created).payload – enthält Details zur Bestellung, Sendung, Rücksendung oder Bestandsänderung. Die Struktur entspricht der API-Antwort für das entsprechende Objekt.
signature – nur vorhanden, wenn ein Secret konfiguriert ist. Dies ist eine HMAC‑SHA256-Signatur der gesamten Nutzlast, mit Ausnahme des Feldes signature selbst.
Überprüfung der Signatur
Es ist wichtig sicherzustellen, dass der Webhook von ChannelDock gesendet wurde und die Nutzlast nicht manipuliert wurde. Dies erreichen Sie, indem Sie die von ChannelDock bereitgestellte Signatur mit Ihrer eigenen Berechnung vergleichen.
Intern signiert ChannelDock jede Nutzlast, indem ein HMAC‑SHA256-Hash der JSON-Daten mit dem von Ihnen konfigurierten Secret berechnet wird. Der resultierende Hash wird als Feld signature in die Nutzlast eingefügt.
Überprüfung der Signatur in Ihrer Anwendung
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 Secret-Schlüssel zusammen mit der Hash-Methode HMAC-SHA256, um eine neue Signatur zu erstellen. Wenden Sie dies auf die empfangenen JSON-Daten an (ohne das Feld
signature).Hashes vergleichen: Wenn der von Ihnen berechnete Hash genau mit der empfangenen Signatur übereinstimmt, können Sie darauf vertrauen, dass die Nutzlast authentisch und unverändert ist.
Tipps für sichere Verarbeitung
Weisen Sie jedem Webhook ein eigenes Secret zu und wechseln Sie es regelmäßig.
Verwenden Sie eine zeitkonstante Vergleichsfunktion (zum Beispiel
hash_equalsin PHP), um Timing-Angriffe zu verhindern.Führen Sie zusätzliche Prüfungen des Inhalts der Nutzlast durch (zum Beispiel überprüfen Sie, ob die Bestellung existiert), bevor Sie irgendwelche Aktionen ausführen.
Bewährte Verfahren
ChannelDock empfiehlt mehrere 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 Wiederholungen). 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.
Verarbeitung der Nutzlast: 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.