Webhooks

Globe puede enviar notificaciones HTTP POST a su servidor cuando se producen eventos clave en su tienda. Use los webhooks para crear automatizaciones a medida — actualizar su WMS, activar flujos de cumplimiento, enviar notificaciones o sincronizar datos con sistemas externos.

---

Configuración

1. Vaya a Configuración → Webhooks en la administración de Globe.
2. Haga clic en Añadir webhook, introduzca la URL de un endpoint HTTPS y elija los eventos que desea recibir.
3. Copie el secret que se muestra tras la creación — solo se muestra una vez. Guárdelo de forma segura.

---

Estructura del payload

Cada webhook es una solicitud POST con Content-Type: application/json. El cuerpo siempre sigue esta estructura:

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

Campo	Descripción
event	Tipo de evento (ver más abajo)
shopName	El dominio de su tienda de Shopify
sentAt	Marca de tiempo ISO 8601 del momento en que Globe envió la solicitud
deliveryId	UUID único de este intento de entrega — úselo para la deduplicación
data	Datos específicos del evento (ver los eventos más abajo)

---

Eventos

shipping_label.created

Se dispara cuando se genera correctamente una etiqueta de envío para un pedido.

Campos clave en data: orderId, orderName, carrier, trackingNumber, trackingUrl, labelData

Nota

labelData es siempre un PDF codificado en base64.

---

pickup_point.selected

Se dispara cuando se selecciona o se cambia un punto de recogida en un pedido.

Campos clave en data: orderId, orderName, pickupPoint

El campo pickupPoint contiene el objeto completo del punto de recogida, incluidos el nombre, la dirección, las coordenadas GPS y los datos específicos del transportista.

---

pickup_point.not_selected

Se dispara aproximadamente 5 minutos después de la creación del pedido cuando este requiere un punto de recogida pero aún no se ha seleccionado ninguno.

Campos clave en data: orderId, orderName, customerEmail

---

order.cod_paid

Se dispara cuando el transportista confirma que se ha pagado un pedido contra reembolso.

Campos clave en data: orderId, orderName, carrier

---

delivery_status.updated

Se dispara cuando el transportista informa de un cambio en el estado de entrega.

Campos clave en data: orderId, orderName, carrier, status, previousStatus

---

email_reminder.sent

Se dispara cuando Globe envía al cliente un correo de recordatorio para seleccionar el punto de recogida.

Campos clave en data: orderId, orderName, customerEmail, reminderType

---

Inspeccionar los payloads

Para explorar la estructura exacta del payload de cada evento, use webhook.site:

1. Abra webhook.site y copie su URL única.
2. Añádala como endpoint de webhook en Globe (Configuración → Webhooks).
3. Provoque el evento de forma natural en su tienda — realice un pedido de prueba, exporte una etiqueta, etc.
4. El cuerpo completo de la solicitud aparecerá en webhook.site en tiempo real.

---

Verificar las solicitudes

Cada solicitud incluye los siguientes encabezados:

Encabezado	Descripción
X-Globe-Signature	sha256=<hmac> — firma HMAC-SHA256 del cuerpo en bruto de la solicitud, firmada con su secret
X-Globe-Timestamp	Marca de tiempo Unix en segundos — rechace las solicitudes con más de 5 minutos de antigüedad para evitar ataques de repetición
X-Globe-Event	Tipo de evento
X-Globe-Delivery	UUID de la entrega

Ejemplo de verificación 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)
  );
}

Precaución

Use siempre timingSafeEqual — una comparación de cadenas estándar es vulnerable a ataques de temporización.

---

Reintentos y fiabilidad

Globe reintenta las entregas fallidas hasta 7 veces con retroceso exponencial:

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

Su endpoint debe devolver un estado 2xx en un plazo de 10 segundos. Pasado ese tiempo, la solicitud se considera fallida.

Si un endpoint falla repetidamente, Globe suspende temporalmente las entregas durante 24 horas y las reintenta automáticamente. Tras 3 ciclos de suspensión sin ninguna entrega correcta, la suscripción se desactiva. Puede volver a activarla en cualquier momento desde Configuración → Webhooks.