Bestellbenachrichtigungen per Webhook in Ihr eigenes System übernehmen

Es gibt zwei Wege, Bestellungen in Ihr ERP, Ihre Lagersoftware, Ihr Buchhaltungsprogramm oder einen Messaging-Kanal zu übertragen: die API in bestimmten Abständen abzufragen oder einen Webhook zu nutzen, der Sie bei einem Ereignis anruft. Der Webhook ist der zweite Weg: Tritt in Ihrem Shop ein Ereignis ein, sendet SEPETYA eine signierte POST-Anfrage mit JSON-Body an die von Ihnen gewählte Adresse.

In diesem Leitfaden zeigen wir, wie Sie einen Webhook einrichten, die Signatur der eingehenden Anfrage prüfen, wie Wiederholungen funktionieren und wie Sie Fehler beheben. Die Details wurden anhand der API-Dokumentation und des Quellcodes der Plattform überprüft; die verbindliche Referenz finden Sie auf der Entwicklerseite.

Webhook oder API?

Der Webhook sagt Ihnen, was passiert ist; die Details lesen Sie über die API. Das Ereignis bei Anlage einer Bestellung enthält zum Beispiel Bestell-ID, Bestellname, Gesamtbetrag, Währung, Kanal und Kunden-ID; Bestellpositionen und Adressen lesen Sie über die API (GET /api/v1/stores/{storeId}/orders/{id}, mit API-Schlüssel per Authorization: Bearer). In Ihrem Paket müssen die Webhook-Funktion und der API-Zugriff aktiviert sein.

Bedarf	Richtiges Werkzeug
Neue Bestellungen sofort in Ihr System übertragen	Webhook
Frühere Bestellungen gesammelt abrufen	API
Nach dem Ereignis alle Details der Bestellung lesen	Per Webhook informiert werden, Details über die API abrufen

Den Ablauf der Bestellungen im Panel (Status, Versand, Rückgabe) beschreiben wir auf der Seite Bestell- und Rückgabeverwaltung; zur kundenseitigen Abwicklung von Rückgaben lesen Sie den Leitfaden Widerrufsrecht und Rückgaberichtlinie.

Webhook einrichten

Klicken Sie auf der Seite Einstellungen › Webhooks auf „Webhook hinzufügen“ und gehen Sie so vor:

1. Endpunkt-Adresse: Sie muss HTTPS verwenden und auf einen öffentlich erreichbaren Server zeigen. SEPETYA sendet keine Anfragen an private Netzwerk-, Loopback- und Link-Local-Adressen (SSRF-Schutz) und folgt keinen Weiterleitungen. Um lokal zu testen, verwenden Sie einen Tunneldienst mit einer öffentlichen HTTPS-Adresse.
2. Ereignisse: Wählen Sie aus den Gruppen Bestellungen, Zahlungen, Erstattungen, Versand, Rücksendeanfragen, Warenkorb, Produkte, Bestand, Kategorien, Kunden, Newsletter, Domains, Shop, Rechnungen und Aktionen. Für eine Bestellintegration genügen meist „Bestellung angelegt“, „Bestellung bezahlt“, „Bestellung versendet“ und „Bestellung erstattet“.
3. Vertriebskanäle (optional): ein Filter nach Herkunft der Bestellung: Onlineshop, Panel, API, Marktplatz oder Import. Wenn Sie welche auswählen, werden nur Bestellereignisse aus diesen Quellen gesendet; ist keiner ausgewählt, alle.
4. Signaturschlüssel: Er beginnt mit whsec_ und wird aus Sicherheitsgründen nur einmal angezeigt, beim Erstellen und beim Erneuern. Speichern Sie ihn in den Umgebungsvariablen Ihres empfangenden Servers; geht er verloren, müssen Sie den Schlüssel erneuern.
5. Testbenachrichtigung: Senden Sie mit „Testbenachrichtigung senden“ ein Ereignis webhook.test; das Ergebnis sehen Sie in den Zustelldetails. Testbenachrichtigungen werden nicht wiederholt, zählen nicht zum Zähler aufeinanderfolgender Fehler und können auch bei deaktiviertem Webhook gesendet werden.

Wie sieht die eingehende Anfrage aus?

Jede Anfrage ist ein POST und trägt die Header nach Standard Webhooks:

Header	Bedeutung
webhook-id	Nachrichten-ID; beginnt mit msg_ und bleibt bei Wiederholungen gleich
webhook-timestamp	Sendezeitpunkt in Unix-Sekunden
webhook-signature	Base64-Signatur, die mit v1, beginnt; während einer Schlüsselerneuerung mehrere durch Leerzeichen getrennte Signaturen
content-type	application/json
user-agent	Besteht aus dem Kurznamen der Plattform und dem Zusatz -Webhooks/1.0

Der Body ist der Ereignis-Umschlag; id enthält die Ereignis-ID, data die ereignisspezifischen Felder. Die Werte im folgenden Bestellbeispiel sind Beispielwerte:

{
  "id": "…Ereignis-ID…",
  "type": "order.created",
  "timestamp": "2026-10-05T09:30:00.000Z",
  "storeId": "…Shop-ID…",
  "apiVersion": "v1",
  "data": {
    "orderId": "…Bestell-ID…",
    "name": "#1001",
    "totalMinor": 129900,
    "currencyCode": "TRY",
    "channel": "storefront",
    "customerId": "…Kunden-ID…"
  }
}

Beträge sind Ganzzahlen in der kleinsten Währungseinheit (totalMinor: 129900 bedeutet 1.299,00 TL).

Signatur prüfen

Das Schema von Standard Webhooks funktioniert so; kein Schritt darf ausgelassen werden:

1. Rohen Body lesen: Verwenden Sie die eingehenden Bytes unverändert, bevor Sie sie in JSON umwandeln. Schon ein einziges abweichendes Leerzeichen im Body macht die Signatur ungültig.
2. Zeit prüfen: Weicht webhook-timestamp um mehr als 5 Minuten von der aktuellen Zeit ab, lehnen Sie die Anfrage ab; das schützt vor Replay-Angriffen.
3. Schlüssel dekodieren: Der Teil nach dem Präfix whsec_ ist Base64; die dekodierten Bytes sind der HMAC-Schlüssel.
4. Signatur berechnen: webhook-id, Punkt, webhook-timestamp, Punkt und der rohe Body werden verkettet; HMAC-SHA256 wird als Base64 geschrieben.
5. Vergleichen: Führen Sie einen zeitkonstanten Vergleich mit einer der v1,-Signaturen im Header durch.

Ein Beispiel mit Node.js und Express (schreiben Sie das Geheimnis nicht in den Code, sondern lesen Sie es aus einer Umgebungsvariablen):

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 5 * 60;

function verify(rawBody, headers) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const key = Buffer.from(SECRET.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key)
    .update(id + '.' + timestamp + '.' + rawBody)
    .digest();
  return signatures.split(' ').some(function (part) {
    const [version, signature] = part.split(',');
    if (version !== 'v1' || !signature) return false;
    const given = Buffer.from(signature, 'base64');
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

const app = express();
app.post('/webhooks', express.raw({ type: 'application/json' }), function (req, res) {
  const rawBody = req.body.toString('utf8');
  if (!verify(rawBody, req.headers)) return res.status(401).end();
  const event = JSON.parse(rawBody);
  // Wurde die webhook-id bereits verarbeitet, überspringen; Arbeit in die Warteschlange legen und sofort antworten
  res.status(204).end();
});
app.listen(3000);

Beim Erneuern des Schlüssels wählen Sie eine Übergangszeit zwischen 0 und 168 Stunden: In dieser Zeit wird jede Anfrage sowohl mit dem alten als auch mit dem neuen Schlüssel signiert, und der Header enthält zwei v1,-Signaturen. Ihr Empfänger prüft mit dem Schlüssel, den er kennt; so verläuft der Schlüsselwechsel ohne Unterbrechung.

Antworten: Erfolg, Zeitüberschreitung und Wiederholungen

Eine Zustellung mit 2xx-Antwort ist erfolgreich. SEPETYA wartet 10 Sekunden auf die Antwort; die Spezifikation von Standard Webhooks empfiehlt 15 bis 30 Sekunden, Ihr Endpunkt muss also schneller reagieren: Legen Sie das Ereignis in eine Warteschlange, antworten Sie sofort mit 2xx und erledigen Sie die aufwendige Arbeit danach. Eine Weiterleitungsantwort (3xx) gilt als Fehlschlag und wird nicht verfolgt; vom Antwort-Body werden höchstens 64 KB gelesen, und eine kurze Zusammenfassung wird in das Zustellprotokoll geschrieben.

Fehlgeschlagene Zustellungen werden in wachsenden Abständen wiederholt; insgesamt gibt es 8 Versuche, und zwischen erstem und letztem Versuch vergehen etwa 24 Stunden:

Fehlgeschlagener Versuch	Nächster Versuch
1	nach 5 Sekunden
2	nach 5 Minuten
3	nach 30 Minuten
4	nach 2 Stunden
5	nach 5 Stunden
6	nach 8 Stunden
7	nach 8 Stunden
8	Abbruch; die Zustellung wird „Fehlgeschlagen“

• Deduplizieren: webhook-id bleibt bei Wiederholungen gleich. Speichern Sie verarbeitete IDs und antworten Sie bei derselben ID mit 2xx und überspringen Sie sie. Da sich automatische Wiederholungen über etwa 24 Stunden verteilen und manuelle Wiederholungen später kommen können, bewahren Sie die IDs mindestens einen Tag, besser einige Tage auf.
• Nicht auf die Reihenfolge verlassen: Durch Wiederholungen können Ereignisse außer der Reihe ankommen. Stützen Sie den Status nicht auf die Eingangsreihenfolge, sondern auf das Feld timestamp des Ereignisses und den aktuellen Datensatz, den Sie über die API lesen.
• Den richtigen Antwortcode wählen: Bei ungültiger Signatur 401; bei einem vorübergehenden Fehler 5xx, für ein verarbeitetes Ereignis 2xx.

Fehlersuche mit dem Zustellprotokoll

Das Zustellprotokoll jedes Webhooks listet Ereignistyp, Art der Zustellung (Ereignis, Test oder erneute Wiedergabe), Anzahl der Versuche, Antwortcode, Dauer und Zeitpunkt. Die Zustelldetails enthalten den gesendeten Body, eine Zusammenfassung der Antwort, den Zeitpunkt des nächsten Versuchs und das Protokoll der letzten 20 Versuche; die Webhook-Seite zeigt die Zahl der erfolgreichen, fehlgeschlagenen und ausstehenden Zustellungen der letzten 24 Stunden.

• Erneut versuchen: Sendet eine fehlgeschlagene Zustellung sofort erneut mit derselben Nachrichten-ID; bei einer erfolgreichen Zustellung nicht verfügbar.
• Erneut wiedergeben: Sendet denselben Body mit neuer Nachrichten-ID als neue Zustellung; Ihr Empfänger verarbeitet ihn wie ein neues Ereignis. Für erneutes Versuchen und Wiedergeben gilt pro Shop ein Limit von 60 Vorgängen pro Stunde.

Im Protokoll sichtbar	Mögliche Ursache und Lösung
Weiterleitungsantwort (301) wird nicht verfolgt	Die Adresse leitet auf eine andere weiter; geben Sie direkt die endgültige Adresse ein
HTTP 401	Signaturprüfung fehlgeschlagen: Prüfen Sie rohen Body, Schlüssel und Serverzeit; ein Proxy verändert möglicherweise den Body
Zeitüberschreitung	Die Antwort dauerte länger als 10 Sekunden; legen Sie das Ereignis in eine Warteschlange und antworten Sie sofort mit 2xx
Verbindungs- oder Zertifikatsfehler	Die Adresse muss öffentlich erreichbar sein und ein gültiges HTTPS-Zertifikat haben; private Netzwerkadressen werden blockiert

Checkliste für die Empfängerseite

• Der Endpunkt ist eine öffentlich erreichbare HTTPS-Adresse mit gültigem Zertifikat.
• Der Signaturschlüssel liegt in einer Umgebungsvariablen; er wird weder in Code noch in Logs geschrieben.
• Die Signatur wird über den rohen Body und mit zeitkonstantem Vergleich geprüft.
• Der Zeitstempel wird mit einer Toleranz von 5 Minuten geprüft.
• Das Ereignis wird in eine Warteschlange gelegt und in weniger als 10 Sekunden mit 2xx beantwortet.
• Es wird über die webhook-id dedupliziert; IDs werden mindestens einen Tag gespeichert.
• Es wird davon ausgegangen, dass Ereignisse außer der Reihe eintreffen können, und der Status wird über die API gelesen.
• Es sind nur die benötigten Ereignisse und Vertriebskanäle abonniert.
• Testbenachrichtigung und eine echte Bestellung erscheinen im Zustellprotokoll als erfolgreich.
• Das Verfahren zur Schlüsselerneuerung (einschließlich Übergangszeit) ist festgelegt.

Um Ihre Integration, die Bestellungen in Ihr eigenes System überträgt, während der Testphase auszuprobieren, starten Sie kostenlos. Zur Automatisierung auf Seiten von Werbung und Produkt-Feeds lesen Sie auch den Leitfaden zum Produkt-Feed für Google Merchant Center.