Webhooky

Globe může odesílat HTTP POST notifikace na váš server při klíčových událostech ve vašem obchodě. Webhooky vám umožní budovat vlastní automatizace — aktualizovat WMS, spouštět fulfillment, odesílat notifikace nebo synchronizovat data s externími systémy.

---

Nastavení

1. V administraci Globe přejděte na Nastavení → Webhooky.
2. Klikněte na Přidat webhook, zadejte HTTPS URL endpointu a vyberte události, které chcete přijímat.
3. Zkopírujte secret zobrazený po vytvoření — je zobrazen pouze jednou. Uložte ho bezpečně.

---

Struktura payloadu

Každý webhook je POST požadavek s Content-Type: application/json. Tělo vždy odpovídá této struktuře:

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

Pole	Popis
event	Typ události (viz níže)
shopName	Doména vašeho Shopify obchodu
sentAt	ISO 8601 časové razítko odeslání
deliveryId	Unikátní UUID tohoto doručení — použijte pro deduplikaci
data	Data specifická pro danou událost (viz níže)

---

Události

shipping_label.created

Odesláno při úspěšném vygenerování přepravního štítku pro objednávku.

Klíčová pole v data: orderId, orderName, carrier, trackingNumber, trackingUrl, labelData

Poznámka

labelData je vždy PDF zakódované v base64.

---

pickup_point.selected

Odesláno při výběru nebo změně výdejního místa na objednávce.

Klíčová pole v data: orderId, orderName, pickupPoint

Pole pickupPoint obsahuje celý objekt výdejního místa včetně názvu, adresy, GPS souřadnic a dat specifických pro dopravce.

---

pickup_point.not_selected

Odesláno přibližně 5 minut po vytvoření objednávky, pokud objednávka vyžaduje výdejní místo, ale žádné nebylo vybráno.

Klíčová pole v data: orderId, orderName, customerEmail

---

order.cod_paid

Odesláno při potvrzení platby dobírky dopravcem.

Klíčová pole v data: orderId, orderName, carrier

---

delivery_status.updated

Odesláno při změně stavu doručení u dopravce.

Klíčová pole v data: orderId, orderName, carrier, status, previousStatus

---

email_reminder.sent

Odesláno při odeslání e-mailové připomínky výběru výdejního místa zákazníkovi.

Klíčová pole v data: orderId, orderName, customerEmail, reminderType

---

Prozkoumání struktury payloadu

Pro prozkoumání přesné struktury payloadu každé události použijte webhook.site:

1. Otevřete webhook.site a zkopírujte vaši unikátní URL.
2. Přidejte ji jako webhook endpoint v Globe (Nastavení → Webhooky).
3. Přirozeně spusťte událost ve vašem obchodě — zadejte testovací objednávku, exportujte štítek apod.
4. Celé tělo požadavku se zobrazí na webhook.site v reálném čase.

---

Ověření požadavků

Každý požadavek obsahuje následující hlavičky:

Hlavička	Popis
X-Globe-Signature	sha256=<hmac> — HMAC-SHA256 podpis těla požadavku, podepsaný vaším secretem
X-Globe-Timestamp	Unix časové razítko v sekundách — odmítněte požadavky starší než 5 minut (ochrana před replay útoky)
X-Globe-Event	Typ události
X-Globe-Delivery	UUID doručení

Příklad ověření v Node.js:

import crypto from "crypto";

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

  // Odmítnutí starých požadavků (ochrana před replay útoky)
  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)
  );
}

Upozornění

Vždy používejte timingSafeEqual — standardní porovnání řetězců je zranitelné vůči timing útokům.

---

Opakované pokusy a spolehlivost

Globe opakuje neúspěšná doručení až 7× s exponenciálním zpožděním:

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

Váš endpoint musí vrátit 2xx status do 10 sekund. Po uplynutí tohoto času je požadavek považován za neúspěšný.

Při opakovaných selháních Globe dočasně pozastaví doručování na 24 hodin a poté automaticky zkusí znovu. Po 3 cyklech pozastavení bez úspěšného doručení je předplatné deaktivováno. Kdykoli ho můžete znovu aktivovat v Nastavení → Webhooky.