Webhooks

Globe can send HTTP POST notifications to your server when key events occur in your store. Use webhooks to build custom automations — update your WMS, trigger fulfilment workflows, send notifications, or sync data with external systems.

---

Setup

1. Go to Settings → Webhooks in the Globe admin.
2. Click Add webhook, enter an HTTPS endpoint URL, and choose the events you want to receive.
3. Copy the secret shown after creation — it is displayed only once. Store it securely.

---

Payload envelope

Every webhook is a POST request with Content-Type: application/json. The body always follows this structure:

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

Field	Description
event	Event type (see below)
shopName	Your Shopify store domain
sentAt	ISO 8601 timestamp of when Globe sent the request
deliveryId	Unique UUID for this delivery attempt — use for deduplication
data	Event-specific payload (see events below)

---

Events

shipping_label.created

Fired when a shipping label is successfully generated for an order.

Key fields in data: orderId, orderName, carrier, trackingNumber, trackingUrl, labelData

Note

labelData is always a base64-encoded PDF.

---

pickup_point.selected

Fired when a pickup point is selected or changed on an order.

Key fields in data: orderId, orderName, pickupPoint

The pickupPoint field contains the full pickup point object including name, address, GPS coordinates, and carrier-specific data.

---

pickup_point.not_selected

Fired approximately 5 minutes after order creation when the order requires a pickup point but none has been selected yet.

Key fields in data: orderId, orderName, customerEmail

---

order.cod_paid

Fired when the carrier confirms that a cash-on-delivery order has been paid.

Key fields in data: orderId, orderName, carrier

---

delivery_status.updated

Fired when the carrier reports a change in delivery status.

Key fields in data: orderId, orderName, carrier, status, previousStatus

---

email_reminder.sent

Fired when Globe sends a pickup-point selection reminder email to the customer.

Key fields in data: orderId, orderName, customerEmail, reminderType

---

Inspecting payloads

To explore the exact payload structure for each event, use webhook.site:

1. Open webhook.site and copy your unique URL.
2. Add it as a webhook endpoint in Globe (Settings → Webhooks).
3. Trigger the event naturally in your store — place a test order, export a label, etc.
4. The full request body will appear on webhook.site in real time.

---

Verifying requests

Each request includes the following headers:

Header	Description
X-Globe-Signature	sha256=<hmac> — HMAC-SHA256 signature of the raw request body, signed with your secret
X-Globe-Timestamp	Unix timestamp in seconds — reject requests older than 5 minutes to prevent replay attacks
X-Globe-Event	Event type
X-Globe-Delivery	Delivery UUID

Node.js verification example:

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

Caution

Always use timingSafeEqual — a standard string comparison is vulnerable to timing attacks.

---

Retries & reliability

Globe retries failed deliveries up to 7 times with exponential backoff:

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

Your endpoint must return a 2xx status within 10 seconds. After that the request is treated as failed.

If an endpoint fails repeatedly, Globe temporarily suspends deliveries for 24 hours and retries automatically. After 3 suspension cycles with no successful delivery the subscription is disabled. You can re-enable it at any time from Settings → Webhooks.