API: avisos automáticos (webhooks)

​

Dar de alta un destino

​

Eventos

• Sólo se avisan los pedidos creados por la API.
• ready_to_ship, delivery_failed y la vuelta de on_hold a pending_payment no tienen evento propio: los ves en el status del próximo aviso o con GET /orders/:id.
• No hay avisos de productos: un evento product.updated todavía no existe.
• Volver a entrar al mismo estado no se avisa dos veces. Si un pedido se pausa, se reanuda y se vuelve a pausar por el mismo motivo, recibís un solo order.on_hold. Si necesitás el estado exacto de ahora, pedilo con GET /orders/:id.

​

El cuerpo del aviso

{
  "id": "evt_5f0c3a9e1b7d4c2a8e6f1d3b9a7c5e2f",
  "type": "order.shipped",
  "created_at": "2026-10-04T13:22:10.000Z",
  "order": {
    "id": 1043,
    "number": "GU-1000412",
    "external_id": "woo-k7p2-10432",
    "status": "shipped",
    "hold_reason": null,
    "cancel_reason": null,
    "tracking": {
      "number": "TEST-GU-1000412",
      "url": "https://example.com/envio-de-prueba/TEST-GU-1000412",
      "carrier": "Envío de prueba"
    }
  }
}

​

El aviso de prueba

POST /tu/ruta/de/avisos HTTP/1.1
Content-Type: application/json
webhook-id: evt_test_3f9a1c7e5b2d8a4f6c0e1b9d
webhook-timestamp: 1791120130
webhook-signature: v1,cLcEaKkq4dm9INfGgPgBS6Vaj/e0wq/rwCcN0a80T2k=

{"id":"evt_test_3f9a1c7e5b2d8a4f6c0e1b9d","type":"webhook.test","created_at":"2026-10-04T13:22:10.000Z"}

​

Cómo tiene que responder tu servidor

1. Verificá la firma antes de hacer nada con el contenido (ver Verificar la firma).
2. Respondé cualquier 2xx en menos de 10 segundos. Guardá el aviso, respondé, y procesalo después. No hagas el trabajo pesado antes de contestar.
3. Deduplicá por webhook-id. El mismo aviso puede llegar más de una vez.
4. No dependas del orden de llegada, ni entre pedidos distintos ni dentro de un mismo pedido: order.in_production puede llegar antes que order.paid. El campo status del aviso, o GET /orders/:id, dice dónde está el pedido. Quedate con el último que procesaste por created_at.

​

Reintentos de un aviso

​

Cómo ponerte al día después de una caída

1. Guardá siempre el created_at del último pedido que tenés.
2. Pedí GET /orders?created_after=<ese instante> y seguí con next_cursor hasta que sea null. Son los pedidos que te faltan.
3. Para los pedidos que ya tenías, pedí GET /orders?updated_after=<la última vez que te pusiste al día> y seguí con next_cursor hasta que sea null. Actualizá los que tengan un updated_at más nuevo que el tuyo. Es una sola consulta paginada, en vez de un GET /orders/:id por pedido.

​

Verificar la firma

• Usá el cuerpo crudo, tal como llegó. Si lo convertís a objeto y lo volvés a serializar, la firma no coincide.
• Rechazá el aviso si la firma no coincide.
• Rechazá el aviso si webhook-timestamp difiere en más de 5 minutos de tu reloj.

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300;

function verifyGudinkWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatureHeader = headers["webhook-signature"];
  if (typeof id !== "string" || typeof timestamp !== "string" || typeof signatureHeader !== "string") return false;
  // Sólo dígitos: con "abc", Number() da NaN y la comparación de abajo daría false (pasaría sin mirar la hora).
  if (!/^\d{1,15}$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
  return signatureHeader.split(" ").some((part) => {
    const [version, signature] = part.split(",");
    if (version !== "v1" || typeof signature !== "string" || !/^[A-Za-z0-9+/]+={0,2}$/.test(signature)) return false;
    // Se comparan los BYTES decodificados, con el mismo largo: timingSafeEqual nunca recibe largos distintos.
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

• El timestamp tiene que ser sólo dígitos antes de compararlo con tu reloj.
• La firma se compara como bytes decodificados de base64, con el mismo largo, en tiempo constante. Nunca como texto.

​

Vector de prueba

​

Probar tu destino sin publicarlo

1. Sin red, firmando vos los avisos. Tu verificación no sabe quién firmó: firmá un cuerpo de aviso con el secreto del vector de prueba (o con el de tu destino) y mandáselo a tu ruta local con cualquier cliente HTTP. Así probás la firma, el 401, la deduplicación por webhook-id, un timestamp viejo y cada type, en tus tests y sin internet:
   import crypto from "node:crypto";
   
   function signGudinkWebhook(rawBody, secret, id, timestamp = Math.floor(Date.now() / 1000)) {
     const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
     const signature = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
     return { "content-type": "application/json", "webhook-id": id, "webhook-timestamp": String(timestamp), "webhook-signature": `v1,${signature}` };
   }
   
   Con el cuerpo, el id y el timestamp del vector, webhook-signature tiene que dar exactamente la del vector.
2. Con avisos reales. Exponé tu servidor local con cualquier túnel https que te dé un nombre de host público en el puerto 443, dá de alta esa URL como destino en el panel de pruebas y tocá “Mandar prueba”. Para ver los avisos de cada estado, hacé avanzar un pedido de prueba con la simulación del entorno de pruebas. Cuando termines, borrá ese destino: un túnel apagado acumula fallas y el destino se desactiva.

​

Si no querés usar avisos