Webhooks einrichten: andere Systeme bei neuen Aufträgen sofort informieren

Du willst, dass deine Warenwirtschaft, dein Versandtool oder ein eigenes Skript sofort erfährt, wenn in billware ein Auftrag, ein Kunde oder ein Artikel angelegt, geändert oder gelöscht wird? Dafür gibt es Webhooks. billware schickt dann bei jedem passenden Ereignis die Daten per HTTPS an eine Adresse, die du festlegst. Du brauchst dafür das Zusatzmodul Webhook und einen Endpunkt, der die Daten annimmt. Den Endpunkt baut meist jemand, der programmieren kann. Diese Anleitung zeigt beides: die Einrichtung in billware und was der Endpunkt wissen muss.

Webhook in billware einrichten

1. Öffne „Apps › Webhook“ und klicke auf „neuer Webhook“.
2. Klappe den neuen Eintrag auf und stell den Status auf „aktiviert“.
3. Gib dem Webhook einen Namen, an dem du ihn später wiedererkennst, zum Beispiel „Neue Bestellung an Warenwirtschaft“.
4. Wähle bei „Event“, wann billware senden soll, etwa order.create für neue Aufträge.
5. Trag bei „Endpunkt“ die Adresse ein, die die Daten empfangen soll. Sie muss mit https:// beginnen.
6. Klicke beim „Schlüssel“ auf „neu generieren“ und kopiere den Schlüssel in deinen Endpunkt. Damit prüft er später, ob eine Anfrage wirklich von billware kommt. Jeder Webhook braucht einen eigenen Schlüssel.

   

7. Klicke auf „Speichern“.

Zwei Felder sind optional:

• Verzögerung: Mit einer ganzen Zahl zwischen 0 und 96 legst du fest, wie viele Stunden billware nach dem Ereignis wartet, bevor es sendet. Bei 0 geht der Webhook zeitnah raus. Gesendet werden die Daten so, wie sie beim Ereignis waren.
• Zusätzliche Daten: Über das Plus fügst du Paare aus Key und Value hinzu, die bei jedem Aufruf mitgeschikt werden. Das hilft zum Beispiel, wenn mehrere billware-Konten an denselben Endpunkt senden und du sie auseinander halten willst.

Welche Events es gibt

Das gilt auch für Aufträge, die über einen Import nach billware kommen, etwa vom eBay-Importer. Importierst du viele Aufträge auf einmal, ruft billware den Webhook für jeden einzelnen auf. Soll ein anderes System davon nichts mitbekommen, deaktivier den Webhook vorher. Der CSV-Importer zeigt dir vor dem Start an, welche aktiven Webhooks ein Import auslöst.

Was billware an den Endpunkt schickt

Für jedes Ereignis sendet billware eine POST-Anfrage an den Endpunkt. Der Inhalt ist JSON mit zwei Feldern:

• data enthält den Auftrag, den Kunden oder den Artikel.
• additional_payload enthält die Zusätzlichen Daten aus den Einstellungen als Liste von Einträgen mit key und value.

Dazu kommen zwei Header:

• X-Bw-Event nennt das Event, zum Beispiel order.create.
• X-Bw-Signature enthält die Signatur, mit der dein Endpunkt die Anfrage prüft.

Signatur prüfen

Jeder, der die Adresse deines Endpunkts kennt, könnte ihm Daten schicken. Prüf deshalb bei jeder Anfrage die Signatur, bevor du mit den Daten arbeitest. Die Signatur ist ein HMAC-SHA256 über den unveränderten Inhalt der Anfrage, berechnet mit dem Schlüssel des Webhooks und Base64-kodiert.

1. Lies den Inhalt der Anfrage so, wie er ankommt, bevor du das JSON auswertest.
2. Berechne daraus mit deinem Schlüssel einen HMAC-SHA256 und kodier das Ergebnis mit Base64.
3. Vergleiche den Wert mit dem Header X-Bw-Signature. Stimmen beide nicht überein, verwirf die Anfrage.

So sieht das in PHP aus:

• $body = file_get_contents('php://input');
• $expected = base64_encode(hash_hmac('sha256', $body, $secret, true));
• $signature = $_SERVER['HTTP_X_BW_SIGNATURE'] ?? '';
• if (!hash_equals($expected, $signature)) { http_response_code(401); exit; }
• $payload = json_decode($body, true);

Antworten des Endpunkts: Statuscodes

Antworte also mit 200, sobald du die Daten angenommen hast. Längere Arbeiten, etwa das Anlegen eines Lieferscheins in einem anderen System, erledigst du am besten danach. Weil ein Aufruf wiederholt werden kann, sollte dein Endpunkt damit klar kommen, denselben Auftrag zweimal zu bekommen, zum Beispiel indem er die Auftragsnummer prüft.