Pedidos entrantes

Cuando entra un pedido, tu servidor recibe un POST con el evento order.created, verifica la firma, responde 2xx y lee el pedido completo desde Admin API.

order.created se envía al crear el pedido, antes de confirmar el pago. Si solo quieres pedidos pagados, suscríbete a order.confirmed.

Requisitos

• Un token de Admin con el scope api_admin. Ver Integración con ERP.
• Una URL HTTPS pública. No puede resolver a una red privada o local.
• Node.js, para los ejemplos en JavaScript.

Verifica la firma

Genera un secreto aleatorio y guárdalo en tu servidor como ECOMIQ_WEBHOOK_SECRET. Cada entrega lleva en X-Ecomiq-Signature el valor sha256=<hmac>, el HMAC-SHA256 del cuerpo crudo con ese secreto.

openssl rand -hex 32

import { createHmac, timingSafeEqual } from "node:crypto";

export function isValidSignature(rawBody, header, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = header.replace(/^sha256=/, "");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");

  return a.length === b.length && timingSafeEqual(a, b);
}

Calcula la firma sobre el cuerpo tal como llega, antes de leer el JSON, y descarta el evento si no coincide.

Responde 2xx

Tienes 15 segundos para responder. Cualquier 2xx cierra la entrega; otro estado o un timeout se reintenta. Guarda la entrega, responde y procesa después.

import { createServer } from "node:http";
import { isValidSignature } from "./signature.js";

createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks).toString("utf8");

  const signature = req.headers["x-ecomiq-signature"] ?? "";
  if (
    !isValidSignature(rawBody, signature, process.env.ECOMIQ_WEBHOOK_SECRET)
  ) {
    res.writeHead(401).end();
    return;
  }

  await saveDelivery({
    deliveryId: req.headers["x-ecomiq-delivery"],
    event: req.headers["x-ecomiq-event"],
    body: rawBody,
  });
  res.writeHead(200).end();
}).listen(process.env.PORT);

saveDelivery guarda la entrega en tu cola o tu base de datos.

Registra el endpoint

Registra tu URL para order.created con el secreto de Verifica la firma. Al crearlo se envía un evento webhook.endpoint.test, y el endpoint se guarda solo si tu servidor responde 2xx.

curl -X POST https://api.ecomiq.pe/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pedidos al ERP",
    "url": "https://erp.example.com/webhooks/ecomiq",
    "eventTypes": ["order.created"],
    "secret": "whsec_replace_with_a_random_secret"
  }'

{
  "id": "7204558912004325301"
}

Guarda el id: lo necesitas para reactivar el endpoint. getToken() viene de Pide un token, en la integración con ERP.

Lee el pedido

El cuerpo de order.created es un OrderWebhookModel: trae orderId, orderNumber, state y los totales, sin las líneas. Para leerlas, consulta el pedido; la respuesta incluye items.

curl https://api.ecomiq.pe/api/v1/orders/7204558912004325301 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

Un mismo pedido puede llegar más de una vez, y un reenvío manual trae otro X-Ecomiq-Delivery. Deduplica por orderId y márcalo después de completar el trabajo.

Recupera fallos

Tras 10 fallos consecutivos el endpoint se pausa. Corrige el receptor y reactívalo; luego lista las entregas fallidas y reenvía cada una por su id.

curl -X POST https://api.ecomiq.pe/api/v1/webhooks/endpoints/<endpoint-id>/enable \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

curl "https://api.ecomiq.pe/api/v1/webhooks/deliveries?status=failed&eventType=order.created" \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

curl -X POST https://api.ecomiq.pe/api/v1/webhooks/deliveries/<delivery-id>/retry \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

El reenvío conserva el cuerpo original.

Siguientes pasos