Webhooks

A Globe HTTP POST értesítéseket küldhet a szerverére, amikor kulcsfontosságú események történnek az áruházában. A webhookok segítségével egyedi automatizálásokat építhet — frissítheti a WMS rendszerét, teljesítési folyamatokat indíthat, értesítéseket küldhet, vagy adatokat szinkronizálhat külső rendszerekkel.

---

Beállítás

1. Lépjen a Beállítások → Webhookok menübe a Globe adminisztrációjában.
2. Kattintson a Webhook hozzáadása gombra, adjon meg egy HTTPS végpont URL-t, és válassza ki a fogadni kívánt eseményeket.
3. Másolja ki a létrehozás után megjelenő titkos kulcsot (secret) — ez csak egyszer jelenik meg. Tárolja biztonságosan.

---

A payload burkolója

Minden webhook egy POST kérés Content-Type: application/json fejléccel. A törzs mindig az alábbi struktúrát követi:

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

Mező	Leírás
event	Az esemény típusa (lásd alább)
shopName	A Shopify áruháza domainje
sentAt	ISO 8601 időbélyeg arról, mikor küldte a Globe a kérést
deliveryId	A kézbesítési kísérlet egyedi UUID-je — használja deduplikációhoz
data	Az eseményre jellemző adatok (lásd az eseményeket alább)

---

Események

shipping_label.created

Akkor indul, amikor egy rendeléshez sikeresen létrejön a szállítási címke.

Kulcsfontosságú mezők a data objektumban: orderId, orderName, carrier, trackingNumber, trackingUrl, labelData

Megjegyzés

A labelData mindig base64 kódolású PDF.

---

pickup_point.selected

Akkor indul, amikor egy rendelésen kiválasztanak vagy módosítanak egy csomagátvételi pontot.

Kulcsfontosságú mezők a data objektumban: orderId, orderName, pickupPoint

A pickupPoint mező a teljes csomagátvételi pont objektumot tartalmazza, beleértve a nevet, a címet, a GPS-koordinátákat és a futárszolgálatra jellemző adatokat.

---

pickup_point.not_selected

Nagyjából 5 perccel a rendelés létrehozása után indul, ha a rendeléshez csomagátvételi pont szükséges, de még nem választottak ki egyet sem.

Kulcsfontosságú mezők a data objektumban: orderId, orderName, customerEmail

---

order.cod_paid

Akkor indul, amikor a futárszolgálat visszaigazolja, hogy egy utánvétes rendelést kifizettek.

Kulcsfontosságú mezők a data objektumban: orderId, orderName, carrier

---

delivery_status.updated

Akkor indul, amikor a futárszolgálat a kézbesítési állapot változását jelenti.

Kulcsfontosságú mezők a data objektumban: orderId, orderName, carrier, status, previousStatus

---

email_reminder.sent

Akkor indul, amikor a Globe csomagátvételi pont kiválasztására emlékeztető e-mailt küld az ügyfélnek.

Kulcsfontosságú mezők a data objektumban: orderId, orderName, customerEmail, reminderType

---

A payloadok vizsgálata

Az egyes események pontos payload-struktúrájának felfedezéséhez használja a webhook.site oldalt:

1. Nyissa meg a webhook.site oldalt, és másolja ki az egyedi URL-jét.
2. Adja hozzá webhook végpontként a Globe-ban (Beállítások → Webhookok).
3. Váltsa ki az eseményt természetes módon az áruházában — adjon le egy próbarendelést, exportáljon egy címkét stb.
4. A teljes kéréstörzs valós időben megjelenik a webhook.site oldalon.

---

A kérések ellenőrzése

Minden kérés az alábbi fejléceket tartalmazza:

Fejléc	Leírás
X-Globe-Signature	sha256=<hmac> — a nyers kéréstörzs HMAC-SHA256 aláírása, a titkos kulcsával aláírva
X-Globe-Timestamp	Unix időbélyeg másodpercben — utasítsa el az 5 percnél régebbi kéréseket a visszajátszásos támadások megelőzése érdekében
X-Globe-Event	Az esemény típusa
X-Globe-Delivery	A kézbesítés UUID-je

Node.js ellenőrzési példa:

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)
  );
}

Figyelem

Mindig a timingSafeEqual függvényt használja — a hagyományos szöveg-összehasonlítás sebezhető az időzítéses támadásokkal szemben.

---

Újrapróbálkozások és megbízhatóság

A Globe a sikertelen kézbesítéseket legfeljebb 7 alkalommal próbálja újra, exponenciálisan növekvő várakozási idővel:

30 s → 5 perc → 30 perc → 2 ó → 8 ó → 24 ó → dead letter

A végpontjának 10 másodpercen belül 2xx állapotkódot kell visszaadnia. Ezt követően a kérés sikertelennek minősül.

Ha egy végpont ismételten hibázik, a Globe 24 órára ideiglenesen felfüggeszti a kézbesítéseket, majd automatikusan újrapróbálkozik. Három olyan felfüggesztési ciklus után, amelyben egyetlen kézbesítés sem járt sikerrel, a feliratkozás letiltásra kerül. Bármikor újra bekapcsolhatja a Beállítások → Webhookok menüben.