Webhooki

Globe może wysyłać powiadomienia HTTP POST na Twój serwer, gdy w sklepie wystąpią kluczowe zdarzenia. Dzięki webhookom zbudujesz własne automatyzacje — zaktualizujesz swój WMS, uruchomisz procesy realizacji zamówień, wyślesz powiadomienia lub zsynchronizujesz dane z systemami zewnętrznymi.

---

Konfiguracja

1. W panelu administracyjnym Globe przejdź do Ustawienia → Webhooki.
2. Kliknij Dodaj webhook, podaj adres URL endpointu HTTPS i wybierz zdarzenia, które chcesz otrzymywać.
3. Skopiuj secret wyświetlony po utworzeniu — jest pokazywany tylko raz. Przechowuj go w bezpiecznym miejscu.

---

Struktura payloadu

Każdy webhook to żądanie POST z nagłówkiem Content-Type: application/json. Treść zawsze ma następującą strukturę:

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

Pole	Opis
event	Typ zdarzenia (zobacz poniżej)
shopName	Domena Twojego sklepu Shopify
sentAt	Znacznik czasu ISO 8601 momentu wysłania żądania przez Globe
deliveryId	Unikalny UUID tej próby doręczenia — użyj go do deduplikacji
data	Dane specyficzne dla zdarzenia (zobacz zdarzenia poniżej)

---

Zdarzenia

shipping_label.created

Wyzwalane po pomyślnym wygenerowaniu etykiety wysyłkowej dla zamówienia.

Kluczowe pola w data: orderId, orderName, carrier, trackingNumber, trackingUrl, labelData

Notatka

labelData to zawsze plik PDF zakodowany w base64.

---

pickup_point.selected

Wyzwalane przy wyborze lub zmianie punktu odbioru w zamówieniu.

Kluczowe pola w data: orderId, orderName, pickupPoint

Pole pickupPoint zawiera pełny obiekt punktu odbioru, w tym nazwę, adres, współrzędne GPS i dane specyficzne dla przewoźnika.

---

pickup_point.not_selected

Wyzwalane około 5 minut po utworzeniu zamówienia, jeśli zamówienie wymaga punktu odbioru, ale żaden nie został jeszcze wybrany.

Kluczowe pola w data: orderId, orderName, customerEmail

---

order.cod_paid

Wyzwalane, gdy przewoźnik potwierdzi opłacenie zamówienia z płatnością za pobraniem.

Kluczowe pola w data: orderId, orderName, carrier

---

delivery_status.updated

Wyzwalane, gdy przewoźnik zgłosi zmianę statusu dostawy.

Kluczowe pola w data: orderId, orderName, carrier, status, previousStatus

---

email_reminder.sent

Wyzwalane, gdy Globe wyśle klientowi przypomnienie e-mail o wyborze punktu odbioru.

Kluczowe pola w data: orderId, orderName, customerEmail, reminderType

---

Podgląd payloadów

Aby poznać dokładną strukturę payloadu każdego zdarzenia, użyj serwisu webhook.site:

1. Otwórz webhook.site i skopiuj swój unikalny adres URL.
2. Dodaj go jako endpoint webhooka w Globe (Ustawienia → Webhooki).
3. Wyzwól zdarzenie w naturalny sposób w swoim sklepie — złóż testowe zamówienie, wyeksportuj etykietę itp.
4. Pełna treść żądania pojawi się na webhook.site w czasie rzeczywistym.

---

Weryfikacja żądań

Każde żądanie zawiera następujące nagłówki:

Nagłówek	Opis
X-Globe-Signature	sha256=<hmac> — podpis HMAC-SHA256 surowej treści żądania, podpisany Twoim secretem
X-Globe-Timestamp	Znacznik czasu Unix w sekundach — odrzucaj żądania starsze niż 5 minut, aby zapobiec atakom typu replay
X-Globe-Event	Typ zdarzenia
X-Globe-Delivery	UUID doręczenia

Przykład weryfikacji w 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)
  );
}

Uwaga

Zawsze używaj timingSafeEqual — standardowe porównanie ciągów znaków jest podatne na ataki czasowe.

---

Ponowne próby i niezawodność

Globe ponawia nieudane doręczenia maksymalnie 7 razy z wykładniczym opóźnieniem:

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

Twój endpoint musi zwrócić status 2xx w ciągu 10 sekund. Po tym czasie żądanie jest traktowane jako nieudane.

Jeśli endpoint zawodzi wielokrotnie, Globe tymczasowo wstrzymuje doręczenia na 24 godziny i ponawia próby automatycznie. Po 3 cyklach wstrzymania bez ani jednego udanego doręczenia subskrypcja zostaje wyłączona. Możesz ją w każdej chwili włączyć ponownie w Ustawienia → Webhooki.