Webhooks

#¿Qué es un webhook de Karrito?

Un webhook envía una petición HTTP a tu servidor cuando ocurre un evento configurado en la tienda. Pertenece a Pro y requiere un destino HTTPS accesible y autorizado. Guardar la configuración no acredita una entrega ni que tu servidor haya procesado el evento.

#Configurar

Abre Configuración → Integraciones → Webhooks, elige el destino y los eventos que ofrece el panel. Guarda el secreto de firma de forma privada y utiliza la prueba y los registros de entrega disponibles para comprobar la conexión.

#Eventos documentados

• order.created: creación de un pedido.
• product.created: creación de un producto.
• product.updated: actualización de un producto.
• product.deleted: borrado de un producto.

No se anuncia order.updated como evento de entrega: el flujo revisado no lo despacha. La forma del cuerpo depende del evento. Usa X-Karrito-Event para identificarlo; no presupongas un envoltorio { event, data } para todos los cuerpos.

#Verificar la firma

Las cabeceras incluyen:

La firma es HMAC-SHA256 de timestamp + punto + cuerpo original, usando el secreto del webhook. Conserva los bytes originales: volver a convertir un JSON parseado con JSON.stringify puede cambiar el cuerpo y romper la comprobación.

Ejemplo de verificación en Node.js. La ventana de cinco minutos es una comprobación de frescura del receptor del ejemplo:

import crypto from 'node:crypto';

function verifyKarritoWebhook(rawBody, signature, timestamp, secret, now = Date.now()) {
  if (!secret || typeof signature !== 'string' || typeof timestamp !== 'string') return false;
  if (!/^sha256=[a-f0-9]{64}$/i.test(signature) || !/^\d+$/.test(timestamp)) return false;
  const age = now / 1000 - Number(timestamp);
  if (!Number.isFinite(age) || age < -30 || age > 300) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest();
  const received = Buffer.from(signature.slice(7), 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Con Express, usa express.raw({ type: 'application/json' }) en la ruta del webhook antes de cualquier middleware que transforme ese cuerpo. Después de validar la firma, parsea y valida el JSON antes de procesarlo.

#Entrega y reintentos

El emisor revisado realiza hasta tres intentos, con un plazo de 10 segundos por petición y esperas de 1 y 2 segundos entre intentos. Los errores 4xx, salvo 429, detienen los reintentos. No se promete una cola de reenvío de 30 minutos.

Un 2xx confirma la respuesta del receptor, no su procesamiento de negocio posterior. Si usas una cola propia, responde después de haber guardado el trabajo de forma duradera. Diseña el consumidor para aceptar repeticiones sin duplicar efectos; no hay promesa de entrega exactamente una vez.

Consulta Autenticación y Zapier/n8n.