Ein WooCommerce-Webhook ist eine Nachricht, die dein Shop an einen anderen Dienst sendet, wenn etwas passiert, etwa wenn eine Bestellung erstellt oder aktualisiert wird. Du richtest ihn einmal unter WooCommerce, Einstellungen, Erweitert, Webhooks ein: Du wählst das Event (das Thema, englisch „Topic“), die Adresse, an die er geht (die Zustell-URL), und ein Secret, mit dem jede Nachricht signiert wird. Ab dann liefert WooCommerce die Bestellung jedes Mal an diese Adresse, wenn das Event ausgelöst wird. Die meisten Probleme kommen aus vier Ecken: dem falschen Thema, einem Secret, das auf beiden Seiten unterschiedlich ist, einem Webhook ohne Benutzer, der Bestellungen lesen darf, und Zustellungen, die pausiert oder verzögert sind.
Diese Anleitung erklärt jedes Feld in klaren Worten und geht dann diese Fehler durch.
Was ein Webhook ist, in Shop-Begriffen
Stell ihn dir als automatische E-Mail zwischen zwei Systemen vor. Statt dass ein Mensch deine Bestellungen prüft und irgendwohin kopiert, sendet WooCommerce jede Bestellung in dem Moment, in dem sie sich ändert, an einen Dienst. Der Dienst kann ein Buchhaltungstool sein, ein Fulfillment-Partner oder ein Widget für Verkaufsbenachrichtigungen.
Zwei Dinge machen das besser als Daten von Hand oder per nächtlichem Export zu kopieren:
- Es passiert sofort. Der empfangende Dienst erfährt binnen Augenblicken von einer Bestellung.
- Es lässt sich prüfen. Mit einem Secret kann der Empfänger beweisen, dass die Nachricht aus deinem Shop kam und unterwegs nicht verändert wurde.
Die Felder auf dem Webhook-Bildschirm
| Feld |
Was es bedeutet |
Was du einträgst |
| Name |
Eine Bezeichnung für dich |
Etwas, das sagt, wohin er geht, etwa „Bestellungen an Provedly“ |
| Status |
Aktiv, Pausiert oder Deaktiviert |
Aktiv, sobald du bereit bist |
| Thema (Topic) |
Welches Event eine Zustellung auslöst |
Meist ein Bestell-Thema, siehe unten |
| Zustell-URL |
Wohin WooCommerce die Nachricht sendet |
Die Adresse, die dir der empfangende Dienst gibt, beginnend mit https |
| Secret |
Ein gemeinsamer Wert, mit dem jede Nachricht signiert wird |
Ein langer Wert, den du auch in den empfangenden Dienst einfügst |
| API-Version |
Das Format der Nachricht |
Die aktuelle WP-REST-API-Version, sofern der Dienst nichts anderes sagt |
Es gibt eine Einstellung, die du nicht als Feld siehst, die aber viel ausmacht: Jeder Webhook gehört einem WordPress-Benutzer. WooCommerce baut jede Zustellung, indem es die Bestellung über seine eigene REST API als dieser Benutzer liest. Kann der Benutzer keine Bestellungen lesen, enthält die Zustellung statt der Bestellung einen Fehler.
order.created oder order.updated
Bei diesen beiden Themen geht in den meisten Setups etwas schief.
- order.created wird einmal ausgelöst, wenn die Bestellung zum ersten Mal gespeichert wird. Bei vielen Zahlungsarten passiert das, bevor der Kunde bezahlt hat, die Bestellung kann also noch auf „Zahlung ausstehend“ stehen.
- order.updated wird jedes Mal ausgelöst, wenn sich die Bestellung ändert: wenn die Zahlung durchgeht und der Status auf „In Bearbeitung“ wechselt, wenn du sie als „Abgeschlossen“ markierst, wenn du eine Notiz hinzufügst.
Wenn du nur auf bezahlte Bestellungen reagieren willst, kann order.created allein den Moment der Zahlung verpassen und Bestellungen liefern, die nie bezahlt werden. order.updated sieht die Zahlung, sendet aber dieselbe Bestellung auch mehrmals. Die übliche Lösung ist, auf order.updated zu hören und den empfangenden Dienst zwei Dinge tun zu lassen: Bestellungen ignorieren, deren Status nicht bezahlt ist, und sich merken, welche Bestell-IDs er bereits verarbeitet hat.
Genau das macht Provedly mit WooCommerce. Es erfasst eine Bestellung nur, wenn ihr Status „In Bearbeitung“ oder „Abgeschlossen“ ist (Processing, Completed), und jede Bestell-ID nur einmal, egal wie viele Updates ankommen. Es nimmt auch Zustellungen von order.created an, mit denselben Regeln.
Das Secret und die Signatur
Wenn ein Webhook ein Secret hat, schickt WooCommerce den Nachrichteninhalt und das Secret durch eine Hash-Funktion (HMAC-SHA256) und sendet das Ergebnis in einem Header namens X-WC-Webhook-Signature. Der empfangende Dienst macht dieselbe Berechnung mit seiner Kopie des Secrets. Stimmen beide Ergebnisse überein, kam die Nachricht von jemandem, der das Secret kennt, und wurde unterwegs nicht verändert. Weichen sie ab, sollte der Dienst die Nachricht verwerfen.
Praktische Punkte:
- Das Secret muss auf beiden Seiten identisch sein, einschließlich Groß- und Kleinschreibung und ohne zusätzliche Leerzeichen.
- Wähle einen langen, zufälligen Wert und halte ihn aus Screenshots und Support-Tickets heraus.
- Änderst du es auf einer Seite, brechen die Zustellungen ab, bis du es auch auf der anderen änderst.
Die Signatur ist das, was einer Verkaufsbenachrichtigung erlaubt, ehrlich „Verifizierter Kauf“ zu sagen. Ohne sie könnte jeder, der die Zustell-URL erfahren hat, eine erfundene Bestellung senden. Unser Erklärartikel zu Webhook-Signing-Secrets vergleicht, wie Stripe, Shopify und WooCommerce das machen.
Häufige Fehler und Lösungen
| Was du siehst |
Ursache |
Lösung |
| Der empfangende Dienst bekommt statt der Bestellung einen REST-API-Fehler, oft zu Berechtigungen |
Der Benutzer des Webhooks kann keine Bestellungen lesen, oder der Webhook wurde von einem Skript ohne Benutzer angelegt |
Stell sicher, dass ein Administrator Eigentümer des Webhooks ist. Das Provedly-Plugin weist einen zu, wenn es den Webhook anlegt |
| „Invalid signature“ im Zustellprotokoll |
Die Secrets unterscheiden sich |
Füge auf beiden Seiten dasselbe Secret ein |
| Es kommt gar nichts an |
Der Webhook ist pausiert oder deaktiviert, oder die Zustell-URL hat einen Tippfehler |
Auf Aktiv setzen und die URL erneut kopieren |
| Der Webhook hat sich selbst deaktiviert |
WooCommerce deaktiviert einen Webhook nach wiederholt fehlgeschlagenen Zustellungen |
Die Ursache beheben, dann wieder auf Aktiv setzen |
| Bestellungen kommen Minuten zu spät an |
Zustellungen werden als Hintergrundjobs eingereiht, die laufen, wenn die Website Traffic oder eine geplante Aufgabe bekommt |
Unter WooCommerce, Status, Geplante Aktionen nach ausstehenden Webhook-Jobs sehen |
| Unbezahlte Bestellungen tauchen in einem anderen Tool auf |
Das Thema ist order.created, und das Tool prüft den Status nicht |
order.updated nutzen und nach Status filtern |
WooCommerce führt unter WooCommerce, Status, Protokolle ein Log der Zustellungen. Es zeigt die Antwort, die der empfangende Dienst zurückgeschickt hat, und ist meist der schnellste Weg zu sehen, was schiefgelaufen ist.
Wenn du einen neuen Webhook anlegst, sendet WooCommerce einen kurzen Test-„Ping“ an die Zustell-URL. Ein gut gebauter Empfänger beantwortet ihn, damit der Webhook aktiviert werden kann; er enthält keine Bestellung.
Umsetzung mit Provedly
Du musst nichts davon von Hand einrichten. Das kostenlose Provedly-Plugin legt den Webhook an, wenn du Zustell-URL und Secret auf seiner Einstellungsseite einfügst und auf Speichern klickst: Thema order.updated, aktuelle API-Version, aktiv, mit deinem Secret signiert, im Besitz eines Administrators. Unsere Anleitung zu WooCommerce-Verkaufsbenachrichtigungen führt durch die Einrichtung.
Häufige Fragen
Brauche ich ein Secret an meinem WooCommerce-Webhook?
Nicht, damit WooCommerce ihn sendet, aber du solltest immer eines setzen, wenn der Empfänger es unterstützt. Ohne Secret kann der Empfänger die Nachrichten deines Shops nicht von denen anderer unterscheiden, und eine Verkaufsbenachrichtigung auf Basis unsignierter Nachrichten kann ehrlicherweise nicht als verifiziert bezeichnet werden.
Kann ich mehr als einen Webhook für Bestellungen haben?
Ja. Jeder Dienst bekommt seinen eigenen Webhook mit eigener Zustell-URL und eigenem Secret. Sie stören sich nicht gegenseitig, und wenn du einen pausierst, laufen die anderen weiter.
Sendet ein neuer Webhook meine früheren Bestellungen?
Nein. Ein Webhook wird bei Events ausgelöst, die nach seiner Erstellung passieren, ältere Bestellungen werden also nur gesendet, wenn sie sich ändern, zum Beispiel wenn du eine als „Abgeschlossen“ markierst. Um die Historie zu übernehmen, nutze stattdessen die Importfunktion des empfangenden Dienstes.
Verbinde deine WooCommerce-Bestellungen über einen signierten Webhook im kostenlosen Tarif von Provedly: Konto erstellen.