Resumen de Webhooks

Los webhooks notifican a tu plugin de los eventos a medida que ocurren en la tienda de un comerciante. Cuando se realiza un nuevo pedido, se actualiza un producto o se registra un cliente, Whatalo envía una solicitud HTTP POST a tu webhookUrl con un payload JSON estructurado.

Cómo Funciona

1. Declara los eventos en tu manifiesto whatalo.app.ts
2. Establece tu webhookUrl — Whatalo envía todos los eventos ahí
3. Verifica las firmas en cada solicitud entrante
4. Procesa el payload del evento y responde con 200 OK en menos de 15 segundos

Declaración en el Manifiesto

// whatalo.app.ts
import { defineApp } from "@whatalo/plugin-sdk";

export default defineApp({
  name: "Mi Plugin",
  pluginId: "mi-plugin",
  webhookUrl: "https://mi-plugin.com/api/webhooks",
  webhooks: [
    { event: "order.created", description: "Rastrear nuevos pedidos para cumplimiento" },
    { event: "order.updated", description: "Sincronizar cambios de pedidos" },
    { event: "product.updated", description: "Sincronizar cambios del catálogo" },
    { event: "checkout.completed", description: "Reaccionar a checkouts completados" },
  ],
  // ... rest of manifest
});

Solo declara los eventos que tu plugin realmente maneja. Declarar eventos no utilizados crea carga innecesaria y confunde a los comerciantes que revisan los permisos de tu plugin.

Detalles de Entrega HTTP

Cada entrega de webhook es una solicitud POST con estas características:

Encabezados de la Solicitud

Estructura del Payload

Los bodies de webhooks contienen datos específicos del evento. El nombre del evento se entrega en X-Webhook-Event, no en el body JSON:

{
  "event_id": "evt_01HX4KQMZ7B9XVNR2T6WQFG3P",
  "occurred_at": "2026-03-01T14:30:00.000Z",
  "order": {
    "id": "ord_abc123",
    "status": "pending"
  },
  "store": {
    "id": "sto_abc123",
    "name": "Mi Tienda"
  }
}

Requisitos de Respuesta

Tu endpoint debe responder con HTTP 200 OK dentro de 15 segundos. Cualquier otro código de estado o un timeout se trata como un fallo de entrega.

Whatalo reintenta las entregas fallidas con backoff exponencial:

Las entregas fallidas se intentan hasta 3 veces en total. La lista de delays configurada es 1s, 2s, 4s, pero solo los delays de 1s y 2s ocurren entre los 3 intentos.

Idempotencia

Dado que las entregas pueden reintentarse, tu handler debe ser idempotente — procesar el mismo evento dos veces no debe producir efectos secundarios duplicados.

async function handleOrderCreated(payload: WebhookPayload, context: WebhookHandlerContext) {
  const orderId = payload.order.id;
  const deliveryId = context.deliveryId; // Valor de X-Webhook-Id

  // Check if this delivery has already been processed
  const existing = await db.processedEvents.findUnique({
    where: { deliveryId },
  });

  if (existing) {
    return; // Already processed — skip
  }

  // Process the order
  await fulfilOrder(orderId);

  // Record that this delivery was processed
  await db.processedEvents.create({ data: { deliveryId } });
}

Siguientes Pasos

• Manejo de Webhooks — Handlers del SDK para Next.js, Hono y Express
• Verificación y Seguridad — Verificación de firma y protección contra replay attacks
• Referencia de Eventos — Todos los eventos públicos de webhook