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.status_changed", description: "Sincronizar actualizaciones de estado" },
    { event: "product.updated", description: "Sincronizar cambios del catálogo" },
    { event: "app.installed", description: "Provisionar recursos del comerciante" },
    { event: "app.uninstalled", description: "Limpiar datos del comerciante" },
  ],
  // ... 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

Todos los payloads de webhooks comparten el mismo sobre:

{
  "id": "evt_01HX4KQMZ7B9XVNR2T6WQFG3P",
  "event": "order.created",
  "store": "mi-tienda",
  "timestamp": "2024-03-01T14:30:00Z",
  "data": {
    // Datos específicos del evento
  }
}

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:

Después de 4 reintentos fallidos, la entrega se abandona y se registra.

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) {
  const orderId = payload.data.id;
  const deliveryId = payload.id; // X-Webhook-ID value

  // 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 — Los 13 eventos disponibles