So richten Sie Webhooks in easySales ein: Bestellungen, Versandetiketten und Bestandsänderungen an Ihre Systeme senden
Senden Sie easySales-Ereignisse wie neue Bestellungen, Versandetiketten, Rechnungen und Bestandsänderungen in dem Moment an Ihre eigenen Systeme, in dem sie passieren, und halten Sie die Abonnements am Laufen.
Wofür Webhooks gut sind
Ein Webhook benachrichtigt ein anderes System in dem Moment, in dem in easySales etwas passiert. Wenn eine Bestellung eingeht, ein Versandetikett erstellt wird oder sich ein Bestand ändert, sendet easySales die Details an eine Adresse Ihrer Wahl. So können Ihr ERP, Ihre Buchhaltungssoftware oder Ihr Onlineshop sofort reagieren, statt easySales alle paar Minuten abzufragen.
Öffnen Sie die Seite easy-sales.com/webhooks, während Sie angemeldet sind. Jede Zeile darauf ist ein Abonnement: ein Ereignis, das an eine Adresse gesendet wird.
Drei Dinge vorab:
- Die empfangende Adresse müssen Sie oder Ihr Entwickler bereitstellen. easySales sendet die Daten, und das System unter dieser Adresse entscheidet, was damit geschieht.
- Ein Abonnement, das immer wieder fehlschlägt, schaltet sich selbst ab. Nach 100 fehlgeschlagenen Versuchen stellt easySales das Senden ein und benachrichtigt Sie per E-Mail. Es schaltet sich nicht von selbst wieder ein.
- Solange ein Abonnement abgeschaltet ist, werden keine Ereignisse aufbewahrt. Wenn Sie es wieder einschalten, wird ab diesem Moment wieder gesendet.
Ein Ereignis abonnieren
- Klicken Sie auf Subscribe to webhook.
- Geben Sie unter Url die Adresse ein, die die Daten empfangen soll. Verwenden Sie eine https-Adresse.
- Lassen Sie HTTP method auf POST.
- Wählen Sie unter Webhook das Ereignis aus.
- Geben Sie unter Secret einen Schlüssel mit mindestens 24 Zeichen ein. Ihr System prüft damit, ob die Daten wirklich von easySales stammen.
- Klicken Sie auf Save.
Das Abonnement erscheint unter dem Namen seines Ereignisses. Um dasselbe Ereignis auch an ein zweites System zu senden, abonnieren Sie es erneut mit der anderen Adresse. Eine Adresse lässt sich pro Ereignis nur einmal hinzufügen.
| Ereignis | Auslöser |
|---|---|
| Order created | Eine neue Bestellung geht über einen beliebigen Kanal ein oder wird manuell angelegt. |
| Order updated | An einer Bestellung ändert sich etwas, zum Beispiel Status, Produkte oder Adresse. Dieses Ereignis wird häufig gesendet. |
| Awb created | Für eine Bestellung wird über einen Kurierdienst in easySales ein Versandetikett erstellt. |
| Delivery status updated | Der Kurierdienst meldet einen neuen Zustellstatus für eine Sendung. |
| Invoice created, Storno invoice created | Für eine Bestellung wird eine Rechnung oder eine Stornorechnung ausgestellt. |
| Return created, Return updated | Eine Retoure wird angelegt, oder ihr Status, ihre Produkte, Notizen, Sendungen oder Rechnungen ändern sich. |
| Product created, Product updated | Ein Produkt wird hinzugefügt oder geändert, auch sein Preis. |
| Product stock updated | Der Bestand eines Produkts ändert sich. |
| Category created / updated, Characteristic created / updated | Eine Kategorie oder ein Merkmal wird hinzugefügt oder geändert. |
| Products refresh requested, Stock refresh requested | Für einen Onlineshop wird eine Aktualisierung der Produkte oder des Bestands angefordert. |
| Ticket created, Ticket updated | Unter Kunden → Tickets beginnt eine Unterhaltung mit einem Käufer, oder eine bestehende ändert sich. |
| Account suspended, Account activated | Das easySales-Konto wird gesperrt oder wieder aktiviert. |
Prüfen, was gesendet wurde
Jedes Abonnement zeigt Success oder Failed für das zuletzt gesendete Ereignis und wann es gesendet wurde. Klicken Sie auf More details..., um dieses Ereignis anzusehen:
- Payload sind die Daten, die easySales gesendet hat.
- Response ist die Antwort Ihrer Adresse mit ihrem Statuscode.
- Attempt 2 of 3 | Next attempt: … bedeutet, dass das Senden fehlgeschlagen ist und das Ereignis erneut gesendet wird. Final attempt has been made bedeutet, dass es für dieses Ereignis keine weiteren Versuche gibt.
Hier wird nur das letzte Ereignis jedes Abonnements angezeigt.
Abonnement ändern, pausieren oder entfernen
- Edit ändert die Adresse, die HTTP-Methode oder den geheimen Schlüssel. Um ein anderes Ereignis zu senden, abonnieren Sie dieses Ereignis und entfernen das alte Abonnement.
- Disable pausiert das Abonnement, Enable startet es wieder. Während der Pause wird nichts gesendet, und die Ereignisse aus dieser Zeit werden auch später nicht nachgeliefert.
- Unsubscribe entfernt das Abonnement sofort.
Was Ihr System leisten muss
| Details | |
|---|---|
| Format | JSON, mit den Ereignisdaten unter payload sowie der Abonnement-ID und dem Ereignisnamen unter webhook. |
| Signatur | Der Header Signature enthält einen HMAC-SHA256 des Request-Bodys, erstellt mit Ihrem geheimen Schlüssel. Berechnen Sie ihn über den Body genau so, wie er empfangen wurde. |
| Antwort | Ein beliebiger 2xx-Status innerhalb von 3 Sekunden. Antworten Sie zuerst und verarbeiten Sie die Daten danach. |
| Zertifikat | https-Adressen brauchen ein gültiges Zertifikat. |
| Wiederholungen | Drei Versuche pro Ereignis: der zweite etwa 10 Sekunden nach dem ersten, der dritte etwa 100 Sekunden später. |
| Reihenfolge des Eingangs | Wegen der Wiederholungen können Ereignisse in anderer Reihenfolge ankommen. Verlassen Sie sich auf die Daten im Payload, nicht auf den Zeitpunkt des Eingangs. |
Wenn sich ein Abonnement selbst abschaltet
Jeder fehlgeschlagene Versuch zählt: eine Fehlerantwort, keine Antwort innerhalb von 3 Sekunden oder ein Zertifikatsproblem. Nach 100 fehlgeschlagenen Versuchen wird das Abonnement abgeschaltet, und Sie erhalten die E-Mail „Webhook wurde deaktiviert“. Deren Schaltfläche Webhooks anzeigen öffnet diese Seite.
- Beheben Sie das Problem an der empfangenden Adresse.
- Klicken Sie beim Abonnement auf Enable.
- Rufen Sie die verpassten Änderungen über die easySales API ab, zum Beispiel die in diesem Zeitraum geänderten Bestellungen.
Zugriff für Ihr Team
Ein Teammitglied braucht die Berechtigung Webhooks anzeigen, um die Seite zu öffnen. Damit kann es Abonnements hinzufügen, ändern, pausieren und entfernen.
Wenn etwas nicht stimmt
| Symptom | Was zu tun ist |
|---|---|
| Es kommt nichts mehr an, und beim Abonnement steht Enable | Es wurde nach wiederholten Fehlern abgeschaltet. Korrigieren Sie die Adresse, klicken Sie auf Enable und rufen Sie dann die verpassten Änderungen über die API ab. |
| Das letzte Ereignis zeigt Failed | Öffnen Sie More details... und prüfen Sie den Statuscode und die Antwort Ihrer Adresse. |
| „The secret must be at least 24 characters.“ | Geben Sie einen geheimen Schlüssel mit mindestens 24 Zeichen ein. |
| „The url has already been taken.“ | Diese Adresse empfängt dieses Ereignis bereits. Bearbeiten Sie stattdessen das bestehende Abonnement. |
| Stornorechnungen kommen nicht an | Abonnieren Sie Storno invoice created; Invoice created umfasst nur reguläre Rechnungen. |
| Das empfangende System wird mit Bestellaktualisierungen überflutet | Order updated wird bei jeder Änderung gesendet. Antworten Sie schnell und verarbeiten Sie die Daten im Hintergrund. |