Webhooks

Globe peut envoyer des notifications HTTP POST à votre serveur lorsque des événements clés se produisent dans votre boutique. Utilisez les webhooks pour créer vos propres automatisations — mettre à jour votre WMS, déclencher des processus de traitement des commandes, envoyer des notifications ou synchroniser des données avec des systèmes externes.

---

Configuration

1. Dans l’administration Globe, accédez à Paramètres → Webhooks.
2. Cliquez sur Ajouter un webhook, saisissez l’URL HTTPS de votre point de terminaison et choisissez les événements que vous souhaitez recevoir.
3. Copiez le secret affiché après la création — il n’est affiché qu’une seule fois. Conservez-le en lieu sûr.

---

Structure du payload

Chaque webhook est une requête POST avec l’en-tête Content-Type: application/json. Le corps suit toujours cette structure :

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

Champ	Description
event	Type d’événement (voir ci-dessous)
shopName	Le domaine de votre boutique Shopify
sentAt	Horodatage ISO 8601 de l’envoi de la requête par Globe
deliveryId	UUID unique de cette tentative d’envoi — à utiliser pour la déduplication
data	Données spécifiques à l’événement (voir les événements ci-dessous)

---

Événements

shipping_label.created

Déclenché lorsqu’une étiquette d’expédition est générée avec succès pour une commande.

Champs principaux dans data : orderId, orderName, carrier, trackingNumber, trackingUrl, labelData

Note

labelData est toujours un PDF encodé en base64.

---

pickup_point.selected

Déclenché lorsqu’un point de retrait est sélectionné ou modifié sur une commande.

Champs principaux dans data : orderId, orderName, pickupPoint

Le champ pickupPoint contient l’objet complet du point de retrait, avec le nom, l’adresse, les coordonnées GPS et les données propres au transporteur.

---

pickup_point.not_selected

Déclenché environ 5 minutes après la création de la commande, lorsque celle-ci nécessite un point de retrait mais qu’aucun n’a encore été sélectionné.

Champs principaux dans data : orderId, orderName, customerEmail

---

order.cod_paid

Déclenché lorsque le transporteur confirme qu’une commande en paiement à la livraison a été réglée.

Champs principaux dans data : orderId, orderName, carrier

---

delivery_status.updated

Déclenché lorsque le transporteur signale un changement de statut de livraison.

Champs principaux dans data : orderId, orderName, carrier, status, previousStatus

---

email_reminder.sent

Déclenché lorsque Globe envoie au client un e-mail de rappel pour sélectionner un point de retrait.

Champs principaux dans data : orderId, orderName, customerEmail, reminderType

---

Inspecter les payloads

Pour explorer la structure exacte du payload de chaque événement, utilisez webhook.site :

1. Ouvrez webhook.site et copiez votre URL unique.
2. Ajoutez-la comme point de terminaison de webhook dans Globe (Paramètres → Webhooks).
3. Déclenchez l’événement naturellement dans votre boutique — passez une commande de test, exportez une étiquette, etc.
4. Le corps complet de la requête apparaît sur webhook.site en temps réel.

---

Vérifier les requêtes

Chaque requête inclut les en-têtes suivants :

En-tête	Description
X-Globe-Signature	sha256=<hmac> — signature HMAC-SHA256 du corps brut de la requête, signée avec votre secret
X-Globe-Timestamp	Horodatage Unix en secondes — rejetez les requêtes datant de plus de 5 minutes pour prévenir les attaques par rejeu
X-Globe-Event	Type d’événement
X-Globe-Delivery	UUID de l’envoi

Exemple de vérification en 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)
  );
}

Attention

Utilisez toujours timingSafeEqual — une comparaison de chaînes classique est vulnérable aux attaques temporelles.

---

Nouvelles tentatives et fiabilité

Globe réessaie les envois échoués jusqu’à 7 fois avec un délai exponentiel :

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

Votre point de terminaison doit renvoyer un statut 2xx en moins de 10 secondes. Au-delà, la requête est considérée comme échouée.

Si un point de terminaison échoue de manière répétée, Globe suspend temporairement les envois pendant 24 heures, puis réessaie automatiquement. Après 3 cycles de suspension sans envoi réussi, l’abonnement est désactivé. Vous pouvez le réactiver à tout moment depuis Paramètres → Webhooks.