Webhooks

Globe kann HTTP-POST-Benachrichtigungen an Ihren Server senden, wenn in Ihrem Shop wichtige Ereignisse eintreten. Mit Webhooks bauen Sie eigene Automatisierungen — Ihr WMS aktualisieren, Fulfillment-Abläufe auslösen, Benachrichtigungen versenden oder Daten mit externen Systemen synchronisieren.

---

Einrichtung

1. Gehen Sie in der Globe-Verwaltung zu Einstellungen → Webhooks.
2. Klicken Sie auf Webhook hinzufügen, geben Sie eine HTTPS-Endpunkt-URL ein und wählen Sie die Ereignisse aus, die Sie empfangen möchten.
3. Kopieren Sie das nach der Erstellung angezeigte Secret — es wird nur ein einziges Mal angezeigt. Bewahren Sie es sicher auf.

---

Aufbau des Payloads

Jeder Webhook ist eine POST-Anfrage mit Content-Type: application/json. Der Body folgt immer dieser Struktur:

{
  "event":      "shipping_label.created",
  "shopName":   "your-store.myshopify.com",
  "sentAt":     "2026-01-15T10:30:00.000Z",
  "deliveryId": "b3d1e4f2-9c2a-4f1b-8e3d-1a2b3c4d5e6f",
  "data":       { ... }
}

Feld	Beschreibung
event	Ereignistyp (siehe unten)
shopName	Domain Ihres Shopify-Shops
sentAt	ISO-8601-Zeitstempel des Versands durch Globe
deliveryId	Eindeutige UUID dieses Zustellversuchs — für die Deduplizierung
data	Ereignisspezifischer Payload (siehe Ereignisse unten)

---

Ereignisse

shipping_label.created

Wird ausgelöst, wenn für eine Bestellung erfolgreich ein Versandlabel erzeugt wurde.

Wichtige Felder in data: orderId, orderName, carrier, trackingNumber, trackingUrl, labelData

Hinweis

labelData ist immer ein base64-kodiertes PDF.

---

pickup_point.selected

Wird ausgelöst, wenn ein Abholpunkt für eine Bestellung ausgewählt oder geändert wird.

Wichtige Felder in data: orderId, orderName, pickupPoint

Das Feld pickupPoint enthält das vollständige Abholpunkt-Objekt inklusive Name, Adresse, GPS-Koordinaten und spediteurspezifischen Daten.

---

pickup_point.not_selected

Wird etwa 5 Minuten nach der Bestellerstellung ausgelöst, wenn die Bestellung einen Abholpunkt erfordert, aber noch keiner ausgewählt wurde.

Wichtige Felder in data: orderId, orderName, customerEmail

---

order.cod_paid

Wird ausgelöst, wenn der Spediteur bestätigt, dass eine Nachnahmebestellung bezahlt wurde.

Wichtige Felder in data: orderId, orderName, carrier

---

delivery_status.updated

Wird ausgelöst, wenn der Spediteur eine Änderung des Lieferstatus meldet.

Wichtige Felder in data: orderId, orderName, carrier, status, previousStatus

---

email_reminder.sent

Wird ausgelöst, wenn Globe dem Kunden eine E-Mail-Erinnerung zur Abholpunktauswahl sendet.

Wichtige Felder in data: orderId, orderName, customerEmail, reminderType

---

Payloads untersuchen

Um die genaue Payload-Struktur jedes Ereignisses zu erkunden, verwenden Sie webhook.site:

1. Öffnen Sie webhook.site und kopieren Sie Ihre eindeutige URL.
2. Fügen Sie sie in Globe als Webhook-Endpunkt hinzu (Einstellungen → Webhooks).
3. Lösen Sie das Ereignis auf natürlichem Weg in Ihrem Shop aus — geben Sie eine Testbestellung auf, exportieren Sie ein Label usw.
4. Der vollständige Request-Body erscheint in Echtzeit auf webhook.site.

---

Anfragen verifizieren

Jede Anfrage enthält die folgenden Header:

Header	Beschreibung
X-Globe-Signature	sha256=<hmac> — HMAC-SHA256-Signatur des rohen Request-Bodys, signiert mit Ihrem Secret
X-Globe-Timestamp	Unix-Zeitstempel in Sekunden — weisen Sie Anfragen zurück, die älter als 5 Minuten sind (Schutz vor Replay-Angriffen)
X-Globe-Event	Ereignistyp
X-Globe-Delivery	UUID der Zustellung

Beispiel zur Verifizierung in Node.js:

import crypto from "crypto";

function verifyGlobeWebhook(rawBody, headers, secret) {
  const sig = headers["x-globe-signature"];
  const ts  = headers["x-globe-timestamp"];

  // Reject stale requests (replay attack prevention)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(sig ?? ""),
    Buffer.from(expected)
  );
}

Achtung

Verwenden Sie immer timingSafeEqual — ein gewöhnlicher String-Vergleich ist anfällig für Timing-Angriffe.

---

Wiederholungen & Zuverlässigkeit

Globe wiederholt fehlgeschlagene Zustellungen bis zu 7-mal mit exponentiell wachsendem Abstand:

30 s → 5 min → 30 min → 2 h → 8 h → 24 h → dead letter

Ihr Endpunkt muss innerhalb von 10 Sekunden einen 2xx-Status zurückgeben. Danach gilt die Anfrage als fehlgeschlagen.

Schlägt ein Endpunkt wiederholt fehl, setzt Globe die Zustellungen vorübergehend für 24 Stunden aus und versucht es anschließend automatisch erneut. Nach 3 Aussetzungszyklen ohne erfolgreiche Zustellung wird das Abonnement deaktiviert. Sie können es jederzeit unter Einstellungen → Webhooks wieder aktivieren.