Webhaken in Shoporama

Mit Webhooks können Sie Shoporama so einrichten, dass automatisch eine Benachrichtigung an einen externen Dienst gesendet wird, sobald in Ihrem Shop etwas passiert. Zum Beispiel, wenn eine neue Bestellung erstellt wird, ein Produkt aktualisiert wird oder ein neuer Kunde angelegt wird. Hier erklären wir dir, was Webhooks sind, auf welche Ereignisse du reagieren kannst und wie du sie einrichtest.

Was sind Webhooks?

Ein Webhook ist eine automatische Benachrichtigung, die Shoporama an eine von dir angegebene URL sendet, sobald ein bestimmtes Ereignis eintritt. Stell dir das wie eine „umgekehrte API“ vor. Anstatt dass du Shoporama fragst: „Gibt es neue Bestellungen?“, teilt Shoporama dir dies automatisch mit.

Ohne Webhooks: Dein Dienst fragt Shoporama alle 5 Minuten: „Gibt es neue Bestellungen?“. Das ist ineffizient und verursacht unnötige Belastung.

Mit Webhooks: Shoporama benachrichtigt dich, sobald eine neue Bestellung vorliegt. Das geschieht automatisch, und du musst nicht immer wieder nachfragen.

Verfügbare Webhook-Ereignisse

Du kannst Webhooks für die folgenden Ereignisse einrichten. Beachte, dass die Ereignisnamen einen Unterstrich (order_created) und keinen Punkt verwenden. Die einzige Ausnahme ist das Test-Ereignis test.ping.

Bestell-Ereignisse

Produkt- und Kategorie-Ereignisse

Kunden- und Newsletter-Ereignisse

Checkout-Ereignisse (der Weg des Kunden durch den Checkout)

Erstelle einen Webhook

1. Gehe im linken Menü zu „Integrationen“
2. Klicke auf „Webhooks“
3. Klicke auf „Webhook erstellen“
4. Gib die URL an, die die Webhook-Daten empfangen soll
5. Wählen Sie die Ereignisse aus, auf die Sie achten möchten (Sie können mehrere auswählen)
6. Klicken Sie auf „Speichern“

Sie können auch direkt von der Protokollseite aus ein Testereignis mit dem Ereignis „test.ping“ senden, um zu überprüfen, ob Ihr Empfänger funktioniert.

Format der Webhook-Nutzlast

Wenn ein Ereignis ausgelöst wird, sendet Shoporama eine HTTP-POST-Anfrage mit Daten im JSON-Format an Ihre URL. Alle Webhooks haben dieselbe Struktur:

{
  "event": "order_created",
  "action": null,
  "timestamp": "2026-05-01T10:30:00+02:00",
  "webshop_id": 1234,
  "data": {
    "event": "order_created",
    "time": 1777624200,
    "basket_id": 98765,
    "order_id": 56789
  }
}

Der Inhalt des Feldes „data“ variiert je nach Ereignis. Bei Produkt-, Lager- und Kategorie-Ereignissen entspricht das Datenobjekt dem, was die REST-API für das jeweilige Objekt zurückgibt. Bei Bestell- und Checkout-Ereignissen besteht der Inhalt aus einer kleineren Menge von Schlüsseln, typischerweise „order_id“ und „basket_id“, mit denen du den Rest über die REST-API abrufen kannst. Das Feld „action“ ist bei Produkt-, Lager- und Kategorie-Ereignissen (create, update, delete oder status) ausgefüllt und bei den übrigen Ereignissen null.

HTTP-Header

Jede Webhook-Anfrage enthält die folgenden Header, die Sie zur Authentifizierung und Weiterleitung verwenden können:

• Content-Type: application/json
• X-Webhook-Event, der Name des Ereignisses, z. B. „order_created“
• X-Webhook-Signature, eine HMAC-SHA-256-Signatur im Format „sha256=...“, berechnet aus dem Request-Body und dem geheimen Schlüssel des Webhooks

Signatur verifizieren

Wenn Sie sichergehen möchten, dass die Anfrage tatsächlich von Shoporama stammt, überprüfen Sie den Header „X-Webhook-Signature“ mit dem geheimen Schlüssel, den Sie in Ihrem Webhook im Shoporama-Admin-Bereich einsehen können. Beispiel in PHP:

$payload = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'])) {
    http_response_code(401);
    exit;
}

Antwort Ihres Empfängers

Dein Empfängerdienst muss mit einem HTTP-Status von 2xx (typischerweise 200) antworten, um den Empfang zu bestätigen. Andere Statuscodes werden als Fehler protokolliert, und du kannst fehlgeschlagene Übermittlungen über die Protokollseite erneut senden.

Verwendung von Webhooks

Typische Anwendungsfälle für Webhooks:

• Lagerhotel-Integration: Sende neue Bestellungen automatisch an das Lagerhotel, z. B. bei „paid“
• Slack/Teams-Benachrichtigung: Lass dich über neue Bestellungen in deinem Kanal benachrichtigen, wenn „order_created“ auftritt
• Lagersynchronisierung: Aktualisiere ein externes System, wenn der Lagerbestand sich ändert
• CRM-Synchronisierung: Erstelle den Kunden in Klaviyo, ActiveCampaign oder deinem eigenen CRM bei „customer_created“
• Automatisierung: Lösen Sie Workflows in Zapier, Make oder ähnlichen Diensten aus

Protokolle und erneute Übermittlung

Für jeden Webhook kannst du ein Protokoll aller Zustellungen einsehen (Statuscodes, Dauer, Payload und Fehler). Du kannst nach Ereignistyp, Status und Datum filtern. Fehlgeschlagene Zustellungen können mit einem Klick manuell erneut gesendet werden. Die Protokolle werden regelmäßig automatisch gelöscht.

Fehlgeschlagene Webhooks im Protokoll suchen

Wenn eine Integration plötzlich keine Daten mehr erhält, ist das Webhook-Protokoll der erste Ort, an dem du nachsehen solltest. Das Protokoll speichert jeden einzelnen ausgehenden Aufruf – sowohl die erfolgreichen als auch die fehlgeschlagenen – zusammen mit der genauen Antwort, die Shoporama zurückerhalten hat. Sie öffnen das Protokoll, indem Sie im linken Menü auf „Integrationen“ und „Webhooks“ gehen und neben dem Webhook, den Sie untersuchen möchten, auf „Protokolle“ klicken.

Beginnen Sie mit den vier Kennzahlen

Sobald mindestens ein Aufruf registriert wurde, werden oben auf der Protokollseite vier Zahlen angezeigt, die sich alle auf die letzten 30 Tage beziehen:

• Aufrufe (30 Tage): Wie oft Shoporama versucht hat, deine URL aufzurufen
• Erfolgsquote: Wie hoch der Anteil der Aufrufe ist, die eine 2xx-Antwort zurückerhalten haben
• Durchschnittliche Antwortzeit: die durchschnittliche Antwortzeit in Millisekunden
• Fehler: Anzahl der fehlgeschlagenen Aufrufe

Die Erfolgsquote wird auch direkt in der Webhook-Liste in der Spalte „Erfolgsquote (30 Tage)“ angezeigt, sodass du sofort erkennen kannst, ob etwas nicht stimmt, ohne jeden einzelnen Webhook öffnen zu müssen. Die Markierung ist ab 90 Prozent grün, zwischen 50 und 90 Prozent gelb und unter 50 Prozent rot. Eine Erfolgsquote, die von 100 auf 0 gesunken ist, bedeutet fast immer, dass der Empfänger umgezogen ist, seinen Dienst eingestellt hat oder strengere Sicherheitsmaßnahmen eingeführt hat.

Filtern Sie die fehlgeschlagenen Aufrufe heraus

Unter den Kennzahlen befindet sich das eigentliche Protokoll mit einer Zeile pro Zustellversuch und den Spalten „Zeit“, „Ereignis“, „Status“, „Dauer“ und „Fehler“. Die Status-Markierung ist farbcodiert, sodass Sie die Seite schnell überfliegen können:

• Grün: Der Antwortcode liegt im 2xx-Bereich, und die Zustellung war erfolgreich
• Orange: Der Statuscode liegt im Bereich 400, d. h., Ihr Empfänger hat geantwortet, den Aufruf jedoch abgelehnt
• Rot: alles andere, d. h. Serverfehler im Bereich 500 oder Status 0

Stellen Sie den Filter „Status“ auf „Fehler“ ein und klicken Sie auf „Filtern“. Dann zeigt die Tabelle nur die Anrufe an, die nicht durchgingen. Sie können gleichzeitig die Anzeige nach Ereignis und Zeitraum mit den Feldern „Von“ und „Bis“ eingrenzen, was praktisch ist, wenn Sie sehen möchten, ob das Problem zu einem bestimmten Zeitpunkt begonnen hat. Das Protokoll zeigt jeweils 50 Zeilen an, und du kannst am unteren Rand der Seite weiterblättern.

„Protokoll-Details“ für einen einzelnen Aufruf öffnen

Klicken Sie auf das Augensymbol rechts neben der Zeile, um das Fenster „Protokoll-Details“ mit dem gesamten Verlauf dieses Aufrufs zu öffnen:

• Ereignis, Status, Dauer und Zeit oben
• Fehlermeldung, die nur angezeigt wird, wenn Shoporama überhaupt keine Verbindung zu deinem Server herstellen konnte
• Anfrage-Payload, das genaue JSON, das gesendet wurde
• Anfrage-Header: die mitgesendeten Header, einschließlich der berechneten Signatur
• Antworttext: die Antwort, die Ihr Server zurückgesendet hat

Der Antworttext ist in der Regel das wertvollste Feld, wenn der Status ein 400- oder 500-Code ist. Die meisten Systeme geben den eigentlichen Grund in der Antwort an, zum Beispiel, dass ein Feld fehlt, dass ein Schlüssel abgelaufen ist oder dass die Bestellung bereits existiert. Das Feld wird nur angezeigt, wenn Ihr Server tatsächlich Inhalte zurückgesendet hat, und sehr lange Antworten werden gekürzt.

Wenn Sie den Verdacht haben, dass der Aufruf unterwegs von einer Firewall oder einer WAF blockiert wird, bitten Sie den Betreiber des Servers, nach Aufrufen mit einem User-Agent-Header zu suchen, der mit „Shoporama Webhook“ beginnt. Wenn der Aufruf im Serverprotokoll zu sehen ist, liegt der Fehler beim Empfänger. Ist dies nicht der Fall, wird der Aufruf gestoppt, bevor er ankommt.

Status 0 bedeutet, dass der Aufruf nie angekommen ist

Wenn in der Spalte „Status“ eine 0 steht, hat Shoporama nie eine HTTP-Antwort erhalten. Daher gibt es keinen Statuscode anzuzeigen, und stattdessen ist das Feld „Fehlermeldung“ ausgefüllt. Die vier typischen Ursachen sind:

Testen Sie mit „Test senden“, sobald Sie etwas korrigiert haben

Die Schaltfläche „Test senden“ oben auf der Protokollseite sendet einen Aufruf mit dem Ereignis „test.ping“ an die URL, auf die der Webhook verweist. Das Ergebnis wird sofort im Protokoll angezeigt, genau wie bei einer echten Übermittlung, sodass du „Protokoll-Details“ öffnen und sehen kannst, was passiert ist. Verwende diese Funktion jedes Mal, wenn du etwas auf deiner Seite geändert hast, anstatt darauf zu warten, dass eine echte Bestellung eingeht.

Eine fehlgeschlagene Lieferung erneut senden

Sobald der Fehler behoben ist, kannst du die Lieferungen, die inzwischen fehlgeschlagen sind, erneut senden. Klicke auf das Symbol „Erneut senden“ – den kreisförmigen Pfeil ganz rechts in der Protokollzeile –, dann sendet Shoporama die ursprünglichen Daten erneut an dieselbe URL. Drei Dinge solltest du dabei beachten:

• Die erneute Übermittlung erzeugt eine neue Zeile im Protokoll. Die ursprüngliche Zeile bleibt mit ihrem Fehler erhalten, sodass du immer den gesamten Verlauf sehen kannst.
• Signatur und Zeitstempel werden neu berechnet. Die „X-Webhook-Signature“ stimmt also weiterhin, aber der Zeitstempel im Payload gibt den Zeitpunkt der erneuten Übermittlung an, nicht den des ursprünglichen Vorgangs.
• Der Inhalt selbst ist eine Momentaufnahme zum Zeitpunkt des Ereignisses. Wurde die Bestellung seitdem geändert, sendet die erneute Übermittlung die alte Version. Wenn Sie die aktuellen Daten benötigen, rufen Sie diese stattdessen über die REST-API ab.

Versucht Shoporama es automatisch erneut?

Nein. Für jedes Ereignis gibt es genau einen Zustellversuch. Wenn dein Empfänger nicht antwortet oder einen Fehlercode zurückgibt, wird der Versuch im Protokoll vermerkt, und es geschieht nichts Weiteres. Es erfolgt keine automatische Wiederholung nach einer Minute, einer Stunde oder einem Tag. Wenn du die Zustellung erneut starten möchtest, musst du selbst auf „Erneut senden“ klicken.

Shoporama wartet höchstens 10 Sekunden auf eine Verbindung zu Ihrem Server und insgesamt höchstens 30 Sekunden auf eine Antwort. Ist Ihr Empfänger langsam, kann die Zustellung daher als fehlgeschlagen gewertet werden, auch wenn Ihr System sie bereits verarbeitet hat.

Dies stellt drei Anforderungen an den Entwickler des Empfängers:

1. Antworte schnell. Sende sofort einen 200-Status zurück und speichere den Inhalt bei dir. Verarbeite ihn anschließend, damit aufwendige Abfragen oder ein langsamer Drittanbieter die Zustellung nicht zum Scheitern bringen.
2. Duplikate tolerieren. Sowohl eine erneute Übermittlung als auch ein Ereignis, das mehrmals ausgelöst wird, können dazu führen, dass derselbe Aufruf zweimal erfolgt. Dein Empfänger muss erkennen können, dass die Bestellung bereits bearbeitet wurde, anstatt sie erneut anzulegen.
3. Richten Sie ein Sicherheitsnetz ein. Rufen Sie mehrmals täglich über die REST-API die Daten ab, die Sie möglicherweise verpasst haben, damit Ihnen durch einen einzelnen Ausfall keine Bestellungen verloren gehen. Sie finden oder erstellen den Schlüssel im Leitfaden „API-Schlüssel suchen oder erstellen“.

Wie lange werden die Log-Einträge gespeichert?

Das Webhook-Protokoll speichert jede Lieferung 45 Tage lang, danach wird der Eintrag automatisch gelöscht. Dies ist auch unten auf der Protokollseite angegeben. Die Bereinigung erfolgt automatisch, Sie müssen nichts unternehmen.

In der Praxis bedeutet das zweierlei: Erstens kannst du nur Lieferungen erneut senden, die weniger als 45 Tage alt sind. Wenn du erst im nächsten Quartal feststellst, dass eine Integration ausgefallen war, sind die alten Einträge bereits gelöscht, und du musst die Daten stattdessen über die REST-API abrufen. Zweitens beziehen sich die Kennzahlen oben auf der Seite nur auf die letzten 30 Tage, sodass ein Fehler, der vor zwei Monaten aufgetreten ist, deine Erfolgsquote nicht mehr beeinflusst.

Wenn du Lieferungen aus einem früheren Zeitraum dokumentieren musst, beispielsweise gegenüber einem Wirtschaftsprüfer oder einem Geschäftspartner, speichere diese bei Erhalt in deinem eigenen System. Das Shoporama-Protokoll ist als Tool zur Fehlersuche gedacht, nicht als Archiv.

Häufig gestellte Fragen

Wo finde ich die Webhook-Liste?

Gehe im linken Menü deines Shoporama-Adminbereichs auf „Integrationen “ und klicke auf „Webhooks“. Du kannst auch unseren Leitfaden lesen, um bereits eingerichtete Webhooks in deinem Shop anzuzeigen.

Wie schnell wird der Webhook übermittelt?

Webhooks werden in eine Warteschlange gestellt und automatisch im Hintergrund versendet, in der Regel innerhalb einer Minute. Bei hoher Auslastung kann es einige Minuten dauern; rechnen Sie also nicht damit, dass ein Webhook genau in dem Moment eintrifft, in dem das Ereignis stattfindet.

Gibt es ein „order_sent“-Ereignis?

Nein. Es gibt kein eigenständiges Ereignis für „versendet“. Wenn du eine Bestellung als gesendet markierst, wird „new_status“ ausgelöst. Die Nutzlast enthält nur die „order_id“ und nicht den eigentlichen Status. Achte daher auf das Ereignis und rufe die Bestellung über die REST-API ab, um zu sehen, auf welchen Status sie geändert wurde.

Müssen Ereignisse mit Punkt oder Unterstrich geschrieben werden?

Mit Unterstrich. Richtig: „order_created“. Falsch: „order.created“. Das einzige Ereignis mit Punkt ist „test.ping“, das für Testlieferungen verwendet wird.

Kann ich in einem Webhook auf mehrere Ereignisse abhören?

Ja. Wähle einfach mehrere Ereignisse aus, wenn du den Webhook erstellst oder bearbeitest. Verwende den X-Webhook-Event-Header oder das „event“-Feld in der Payload, um sie in deinem Empfänger zu unterscheiden.

Was passiert, wenn mein Server ausfällt?

Die Zustellung wird als fehlgeschlagen protokolliert. Du kannst sie manuell über die Protokollseite erneut senden, sobald dein Server wieder verfügbar ist. Wir führen keinen automatischen Wiederholungsversuch durch. Richten Sie Ihren Empfänger daher so ein, dass er gelegentliche Ausfälle bei der Zustellung verkraften kann, und rufen Sie fehlende Bestellungen über die REST-API als Backup ab.

Woher weiß ich, dass der Anruf tatsächlich von Shoporama stammt?

Überprüfe den Header „X-Webhook-Signature“ mit dem geheimen Schlüssel deines Webhooks. Dieser wird in deinem Webhook im Shoporama-Adminbereich angezeigt. Vergleiche ihn mit einem HMAC SHA-256 des empfangenen Body-Inhalts. Stimmen die beiden nicht überein, lehne die Anfrage ab.

Kann ich Webhooks zusammen mit der REST-API nutzen?

Ja, und das ist oft eine gute Idee. Verwende Webhooks, um benachrichtigt zu werden, und nutze die REST-API, um vollständige Daten abzurufen oder basierend auf dem Ereignis Aktionen auszuführen.

Wie viele Webhooks kann ich erstellen?

In Shoporama gibt es keine feste Obergrenze. Erstelle so viele, wie du benötigst, aber bereinige die Webhooks, die nicht mehr verwendet werden, um unnötigen Datenverkehr zu stillgelegten URLs zu vermeiden.

Die Erfolgsrate meines Webhooks ist auf 0 gesunken. Was soll ich als Erstes tun?

Öffne die Protokolle des Webhooks, stelle den Filter „Status“ auf „Fehler“ ein und öffne die neueste Zeile über das Augensymbol. Steht im Status „0“, liegt das Problem bei der Verbindung, und das Feld „Fehlermeldung“ gibt Aufschluss darüber, warum. Steht dort 401, 403 oder 404, hat der Empfänger geantwortet, den Aufruf jedoch abgelehnt, und die Erklärung findet sich in der Regel im Antworttext. Wenn du den Fehler behoben hast, klicke auf „Test senden“, um zu überprüfen, ob es funktioniert, und anschließend auf „Erneut senden“ für die Lieferungen, bei denen ein Fehler aufgetreten ist. Wenn du die Fehlermeldung nicht verstehst, mache einen Screenshot der „Protokoll-Details“ und sende ihn an den Entwickler der Integration oder schreibe an support@shoporama.dk.

Meine URL funktioniert im Browser einwandfrei, aber das Protokoll zeigt einen SSL-Fehler an. Was ist das Problem?

Shoporama überprüft das Zertifikat auf deiner Empfängerseite und akzeptiert weder selbstsignierte Zertifikate noch eine unvollständige Zertifikatskette. Browser sind da toleranter, da sie fehlende Zwischenzertifikate selbst von anderen Quellen abrufen können; daher kann dieselbe URL in einem Browser durchaus einwandfrei angezeigt werden. Bitte den Betreiber des Servers, zu überprüfen, ob die gesamte Zertifikatskette vorhanden ist und das Zertifikat nicht abgelaufen ist.

Mein Lagerhotel hat die Bestellung nicht erhalten. Kann ich sie erneut senden?

Ja. Suchen Sie im Protokoll die Zeile zu dem Zeitpunkt, zu dem die Bestellung erstellt wurde, und klicken Sie auf das Symbol „Erneut senden“. Vereinbaren Sie mit dem Lagerbetreiber, dass es kein Problem ist, denselben Auftrag zweimal zu erhalten, damit Sie kein doppeltes Kommissionieren riskieren. Ist die Lieferung älter als 45 Tage, wurde der Protokolleintrag gelöscht, und der Auftrag muss manuell weitergeleitet werden.

Werde ich benachrichtigt, wenn ein Webhook nicht mehr funktioniert?

Nein, Shoporama sendet von sich aus keine Warnung. Allerdings wird die Erfolgsquote der letzten 30 Tage direkt in der Webhook-Liste angezeigt, und die Markierung wird rot, sobald weniger als die Hälfte der Aufrufe erfolgreich ist. Wenn du mehrere Shops betreibst, ist es empfehlenswert, die Liste einmal pro Woche durchzugehen oder deinen eigenen Empfänger Alarm schlagen zu lassen, falls er seit 24 Stunden nichts von einem Shop gehört hat.

Benötigen Sie Hilfe? Kontaktieren Sie uns unter support@shoporama.dk.