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.
| Evento | Cuándo |
|---|---|
order.created | Se creó un pedido. Si nace pagado, también llega order.paid. |
order.paid | El pedido pasó a paymentStatus = PAGADO. |
order.status_changed | Cambió status. data.previousStatus y data.status dicen de dónde a dónde. Valores: PENDIENTE, CONFIRMADO, PREPARANDO, EN_CAMINO, ENTREGADO, CANCELADO. |
order.proof_uploaded | El 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.
{
"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):
- «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. - 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. - 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).
- «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 mismoTiendy-Event-Idy 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:
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
2xxrá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 porTiendy-Event-Id(es el mismoiddel cuerpo). - Sin orden garantizado. Un
order.paidpuede llegar antes que suorder.created, y un reintento puede llegar después de un evento más nuevo.createdAtes la hora del evento, no la de la entrega. - El evento es un aviso, no el estado. El
orderdel cuerpo es una foto del momento del evento. Para el estado actual, consultarGET /orders/{token}con elpublicTokendel 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.