Browse all articles

Webhooks in ChannelDock einrichten

Last updated

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. Ist ein Secret gesetzt, signiert ChannelDock jede Zustellung mit einer HMAC-SHA256-Signatur im Header X-Channeldock-Signature, sodass Sie überprüfen können, ob eine Anfrage wirklich von ChannelDock stammt.

Einrichten eines Webhooks

  1. 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.

  2. Erstellen Sie einen neuen Webhook: Klicken Sie auf Neuen Webhook erstellen. Es erscheint ein Fenster „Webhook-Konfiguration“.

  3. 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.picking, order.picked, order.deleted, shipment.created, stock.updated, return.created, return.handled und return.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 jede Zustellung zu signieren, damit Sie überprüfen können, dass die Anfrage von ChannelDock stammt und unterwegs nicht verändert wurde.

  4. 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>" (veraltet, siehe unten)  
}
  • 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 jeweilige Objekt.
  • signature – nur vorhanden, wenn ein Secret konfiguriert ist. Dies ist die alte Signatur und gilt als veraltet; überprüfen Sie stattdessen den Header X-Channeldock-Signature.

Überprüfung der Signatur

Ihre Webhook-URL muss öffentlich erreichbar sein, und die Anfrage enthält keinen weiteren Nachweis darüber, wer sie gesendet hat — keinen API-Schlüssel, kein Passwort. Alles, was diese URL erreicht, sieht für Ihren Endpunkt daher wie eine echte ChannelDock-Zustellung aus: eine URL, die über eine Logdatei, einen Proxy oder ein Support-Ticket nach außen gelangt ist, oder eine frühere Zustellung, die jemand mitgeschnitten und erneut gesendet hat. Wenn Sie ungeprüft auf den Inhalt reagieren, könnte ein gefälschtes stock.updated Ihren Bestand auf null setzen oder ein gefälschtes order.updated eine Bestellung in Ihrem eigenen System als versandt markieren.

Die Signatur ist dieser fehlende Nachweis. Nur Sie und ChannelDock kennen das Secret, also können nur Sie beide einen Wert erzeugen, der zu der Zustellung passt, die Sie vor sich haben.

Sobald Sie ein Webhook-Secret setzen, kommt jede Zustellung für diesen Webhook mit einem zusätzlichen HTTP-Header an:

X-Channeldock-Signature: sha256=8b415f2c0cd241a21109e007942b6ce43cbfcf97f7b2d7829084258c0ae0a66f

Dieser Wert ist ein HMAC-SHA256-Hash des Anfragetextes, berechnet mit Ihrem Secret als Schlüssel. Sie berechnen denselben Hash auf Ihrer Seite und prüfen, ob beide identisch sind. Ist kein Secret gesetzt, wird der Header nicht gesendet.

Überprüfung der Signatur in Ihrer Anwendung

  1. Lesen Sie den Rohtext. Nehmen Sie den Anfragetext als Text oder Bytes, bevor das JSON geparst wird. Die meisten Frameworks parsen das JSON und verwerfen den Originaltext, fordern Sie ihn daher ausdrücklich an: php://input in PHP, $request->getContent() in Laravel, request.get_data() in Flask, request.body in Django, request.raw_post in Rails oder express.json({ verify: (req, res, buf) => { req.rawBody = buf } }) in Express.
  2. Lesen Sie den Header. Nehmen Sie X-Channeldock-Signature und entfernen Sie das Präfix sha256=. Suchen Sie den Header ohne Beachtung der Groß- und Kleinschreibung — je nach Verbindung kommt er als x-channeldock-signature an.
  3. Berechnen Sie Ihren eigenen Hash. Einen HMAC-SHA256 des Rohtextes mit Ihrem Webhook-Secret als Schlüssel, hexadezimal geschrieben. In PHP ist das hash_hmac('sha256', $raw, $secret).
  4. Vergleichen Sie mit einer Funktion mit konstanter Laufzeit wie hash_equals. Sind beide identisch, ist die Zustellung echt und Sie können sie verarbeiten. Andernfalls geben Sie HTTP 401 zurück und ignorieren den Inhalt. Parsen Sie das JSON erst, nachdem dieser Schritt erfolgreich war.

Wichtig: hashen Sie den Text genau so, wie Sie ihn empfangen haben. Eine Signatur ist ein Hash von Bytes, nicht von der Bedeutung des JSON. Parsen Sie das JSON also nicht, um es danach wieder in Text umzuwandeln und zu hashen. Zwei Sprachen können JSON schreiben, das genau dasselbe bedeutet, aber nicht derselbe Text ist: PHP schreibt einen Schrägstrich als c\/o, wo Node.js und Python c/o schreiben. Das liest sich als identische Daten zurück, ergibt aber einen völlig anderen Hash. Entfernen Sie auch das Feld signature nicht vor dem Hashen — es gehört zu dem Text, der signiert wurde.

Das veraltete signature-Feld

Bevor es den Header gab, setzte ChannelDock ein signature-Feld in den Text selbst. Es wird weiterhin unverändert gesendet, bestehende Anbindungen funktionieren also weiter, aber es gilt als veraltet. Zur Überprüfung müssten Sie das Feld entfernen und das übrige JSON wieder als Text aufbauen, genau so wie PHP es schreibt, einschließlich der Eigenart von PHP, / als \/ zu schreiben. In einer anderen Sprache ist das kaum korrekt hinzubekommen.

Bauen Sie neue Anbindungen auf den Header. Überprüfen Sie heute das Feld, bricht nichts: beide werden bei jeder Zustellung gesendet, Sie können also wechseln, wann es Ihnen passt. Die beiden Werte sind nie gleich, weil sie unterschiedliche Daten abdecken — vergleichen Sie sie daher niemals miteinander.

Tipps für sichere Verarbeitung

  • Weisen Sie jedem Webhook ein eigenes Secret zu und wechseln Sie es regelmäßig.
  • Verwenden Sie eine Vergleichsfunktion mit konstanter Laufzeit (zum Beispiel hash_equals in PHP oder crypto.timingSafeEqual in Node.js), um Timing-Angriffe zu verhindern.
  • Überprüfen Sie die Signatur, bevor Sie mit dem Inhalt der Nutzlast arbeiten.
  • Führen Sie zusätzliche Prüfungen am Inhalt der Nutzlast durch (überprüfen Sie zum Beispiel, ob die Bestellung existiert), bevor Sie 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.

Was this helpful?