Warum Webhooks verwenden?
ChannelDock bietet Webhooks, 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, Bestandsmengen sich ändern oder eine Rücksendung erfasst wird. Webhooks helfen Ihnen, Prozesse zu automatisieren und unnötige API-Anfragen zu reduzieren.
Hauptmerkmale
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 Schlüssel, um eine digitale Signatur zu berechnen, sodass 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. Ein Fenster „Webhook-Konfiguration“ erscheint.
Füllen Sie die Felder aus:
Name des Webhooks: Wählen Sie einen beschreibenden 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.
Ereignis, das den Webhook auslöst: Wählen Sie den Ereignistyp, über den 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-Geheimnis (optional, aber empfohlen): Geben Sie Ihr eigenes Geheimnis an oder klicken Sie auf Generieren, um ein starkes Geheimnis zu erstellen. ChannelDock verwendet dieses Geheimnis, um eine HMAC‑SHA256-Hashsignatur zu berechnen, damit Sie die Nutzlast verifizieren 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 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 Geheimnis konfiguriert ist. Dabei handelt es sich um eine HMAC‑SHA256-Signatur der vollständigen Nutzlast, ausgenommen das Feld
signatureselbst.
Ü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 Geheimnis 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 geheimen Schlüssel zusammen mit der Hashmethode 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 exakt mit der erhaltenen 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 Geheimnis zu und wechseln Sie es regelmäßig.
Verwenden Sie eine zeitkonstante Vergleichsfunktion (z. B.
hash_equalsin PHP), um Timing-Angriffe zu verhindern.Führen Sie zusätzliche Prüfungen des Inhalts der Nutzlast durch (z. B. überprüfen Sie, ob die Bestellung existiert), bevor Sie Aktionen ausführen.
Empfohlene Vorgehensweisen
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 (z. B. aufgrund von Netzwerkproblemen oder Wiederholungsversuchen). Stellen Sie sicher, dass Ihre Verarbeitungslogik idempotent ist, damit doppelte Nachrichten nicht zu doppelter Arbeit führen.
Monitoring: Verwenden Sie das ChannelDock-Dashboard, um den Status Ihrer Webhooks zu überwachen und Fehler zu identifizieren.
Nutzlastverarbeitung: Stellen Sie sicher, dass Ihr Endpunkt große Nutzlasten verarbeiten kann und innerhalb einer angemessenen Zeit (≤ 5 Sekunden) antwortet. Webhooks werden nach zehn fehlgeschlagenen Zustellversuchen automatisch deaktiviert.
Dieser Artikel wurde automatisch aus dem Englischen übersetzt.