Guías · Operar

Webhooks

Firma, reintentos y el contrato del receptor.

Tiendy avisa por POST a una URL https del comercio cuando cambia un pedido de la tienda. Llegan los pedidos de todos los canales (storefront de Tiendy, esta API, marketplace, panel y caja), y cada evento dice de cuál vino en data.order.source (STOREFRONT, STOREFRONT_API, MARKETPLACE, ADMIN, POS, o null en pedidos viejos). Solo plan PRO.

EventoCuándo
order.createdSe creó un pedido. Si nace pagado, también llega order.paid.
order.paidEl pedido pasó a paymentStatus = PAGADO.
order.status_changedCambió status. data.previousStatus y data.status dicen de dónde a dónde. Valores: PENDIENTE, CONFIRMADO, PREPARANDO, EN_CAMINO, ENTREGADO, CANCELADO.
order.proof_uploadedEl comprador subió el comprobante de pago.

Un endpoint puede suscribirse a algunos eventos; sin lista recibe todos. Un evento se genera solo para los endpoints activos en ese momento, y solo si la tienda está en el plan PRO: lo que pasa con un endpoint pausado o con la tienda fuera del plan no se envía después.

JSON
{
  "id": "7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11",
  "type": "order.status_changed",
  "createdAt": "2026-11-03T15:04:05.000Z",
  "storeId": "…",
  "data": {
    "order": { "id": 1234, "status": "PREPARANDO", "paymentStatus": "PAGADO", "total": 115000, "source": "STOREFRONT_API", "…": "…" },
    "previousStatus": "PENDIENTE",
    "status": "PREPARANDO"
  }
}

data.order es el mismo OrderView de GET /orders/{token}, sin metaPurchase y con source: sin datos del comprador, sin costos, sin publicToken. Un pago con tarjeta confirmado genera order.paid y, si el pedido estaba PENDIENTE, order.status_changed a PREPARANDO. Es una foto del pedido en el momento del evento; para el estado actual, consultar la API.

Registrar un endpoint

El comercio da de alta sus endpoints en el panel de Tiendy, en Configuración → API → Webhooks (hace falta permiso de edición de Configuración; con permiso de solo lectura se ven la lista y el historial de envíos):

  1. «Agregar webhook»: la URL (https, pública), una descripción opcional y los eventos. «Todos los eventos» (el default) también recibe los que se agreguen más adelante. Hasta 10 endpoints por tienda.
  2. Al guardar, el panel muestra una sola vez el secreto de firma whsec_…. Copiarlo y guardarlo en el receptor: Tiendy no lo vuelve a mostrar, y en la lista solo aparecen sus últimos 4 caracteres.
  3. Desde la lista se puede editar, pausar o activar (al pausar, los envíos que ya estaban pendientes quedan en espera y salen al reactivarlo, dentro de los 3 días; los eventos que ocurren mientras está pausado no se generan), rotar el secreto (el anterior deja de funcionar enseguida y el nuevo se muestra una vez) y eliminar (se borra también su historial).
  4. «Ver envíos» muestra cada entrega con su evento, Tiendy-Event-Id, estado (pendiente, entregado, reintentando, fallido), intentos y la última respuesta. «Reenviar» vuelve a mandar una entrega con el mismo Tiendy-Event-Id y el mismo cuerpo, así que un receptor que descarta repetidos la trata igual; no se puede reenviar un evento de más de 3 días, uno de un endpoint pausado ni uno que ya está en cola. El historial conserva los envíos entregados y los fallidos durante 30 días.

Verificar la firma

Cada request trae Tiendy-Event-Id, Tiendy-Event-Type y Tiendy-Signature: t=<unix>,v1=<hex>, donde v1 es el HMAC-SHA256 con el secreto del endpoint (whsec_…, se muestra una sola vez al crearlo) sobre <t>.<cuerpo crudo>. Verificar sobre el cuerpo tal como llegó, antes de parsear el JSON, comparar en tiempo constante y rechazar un t con más de 5 minutos de diferencia:

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

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Entrega y reintentos

  • Responder 2xx rápido y procesar después. Cualquier otra respuesta, una redirección (no se siguen) o 10 segundos sin respuesta es un intento fallido.
  • Hasta 8 intentos, con esperas de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h. Un evento sin entregar a los 3 días se descarta.
  • Si la tienda deja el plan PRO, los eventos pendientes no se envían: quedan en espera y salen si vuelve al plan antes de los 3 días. Los pedidos que cambian mientras está fuera del plan no generan eventos.

Contrato del receptor

  • Al menos una vez. El mismo evento puede llegar más de una vez, incluso después de un 2xx. Descartar repeticiones por Tiendy-Event-Id (es el mismo id del cuerpo).
  • Sin orden garantizado. Un order.paid puede llegar antes que su order.created, y un reintento puede llegar después de un evento más nuevo. createdAt es la hora del evento, no la de la entrega.
  • El evento es un aviso, no el estado. El order del cuerpo es una foto del momento del evento. Para el estado actual, consultar GET /orders/{token} con el publicToken del pedido y actuar sobre esa respuesta.
  • La URL tiene que resolver a una dirección pública; una URL interna o privada nunca recibe nada.