Testing de webhooks

Desarrollo local

Usa ngrok o smee.io para recibir webhooks en local:

ngrok http 3000
# Copia la URL HTTPS y regístrala como webhook endpoint

También puedes ver el historial de entregas en Admin → Webhooks → Ver entregas.

Flujo con ngrok

1. Inicia tu servidor local (puerto 3000).
2. Ejecuta ngrok http 3000 y copia la URL https://xxxx.ngrok.io.
3. Registra el webhook con esa URL:

   curl -X POST https://app.omnibuy.net/api/v1/webhooks \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://xxxx.ngrok.io/webhooks/omnibuy",
       "events": ["orders.order.created"],
       "secret": "test_secret_123"
     }'

4. Genera un evento (crea una orden desde el storefront o la API).
5. Revisa la consola de ngrok en http://localhost:4040 para inspeccionar el request.

Alternativa: smee.io

Si no puedes usar ngrok (red corporativa, firewall), smee.io actúa como proxy público:

1. Crea un canal en https://smee.io/new.
2. Usa la URL del canal como endpoint del webhook.
3. Instala el cliente de smee para reenviar a tu local:

   npx smee --url https://smee.io/xxxxx --target http://localhost:3000/webhooks/omnibuy

Payloads de ejemplo

orders.order.created

{
  "specversion": "1.0",
  "id": "01JABC111...",
  "source": "/omnibuy/orders",
  "type": "orders.order.created",
  "time": "2026-04-08T12:00:00Z",
  "datacontenttype": "application/json",
  "tenantid": "00000000-0000-0000-0000-000000000001",
  "data": {
    "id": "ord_9x8y7z",
    "status": "pending",
    "total": 15990,
    "currency": "PEN",
    "customer": { "email": "[email protected]", "name": "Juan Pérez" },
    "items": [
      { "sku": "PROD-001", "name": "Camiseta Logo", "qty": 2, "price": 7995 }
    ],
    "created_at": "2026-04-08T12:00:00Z"
  }
}

payments.payment.captured

{
  "specversion": "1.0",
  "id": "01JABC222...",
  "source": "/omnibuy/payments",
  "type": "payments.payment.captured",
  "time": "2026-04-08T12:05:30Z",
  "datacontenttype": "application/json",
  "tenantid": "00000000-0000-0000-0000-000000000001",
  "data": {
    "id": "pay_abc123",
    "order_id": "ord_9x8y7z",
    "amount": 15990,
    "currency": "PEN",
    "method": "card",
    "status": "captured",
    "captured_at": "2026-04-08T12:05:30Z"
  }
}

orders.order.fulfilled

{
  "specversion": "1.0",
  "id": "01JABC333...",
  "source": "/omnibuy/orders",
  "type": "orders.order.fulfilled",
  "time": "2026-04-09T08:00:00Z",
  "datacontenttype": "application/json",
  "tenantid": "00000000-0000-0000-0000-000000000001",
  "data": {
    "id": "ord_9x8y7z",
    "status": "fulfilled",
    "tracking_number": "PE123456789",
    "carrier": "Serpost",
    "fulfilled_at": "2026-04-09T08:00:00Z"
  }
}

products.product.updated

{
  "specversion": "1.0",
  "id": "01JABC444...",
  "source": "/omnibuy/products",
  "type": "products.product.updated",
  "time": "2026-04-08T14:30:00Z",
  "datacontenttype": "application/json",
  "tenantid": "00000000-0000-0000-0000-000000000001",
  "data": {
    "id": "prod_xyz",
    "sku": "PROD-001",
    "name": "Camiseta Logo",
    "price": 8995,
    "stock": 42,
    "updated_at": "2026-04-08T14:30:00Z"
  }
}

Reintentar entregas fallidas

Si una entrega falla (tu endpoint estuvo caído, timeout, etc.), puedes reintentarla manualmente:

1. Ve a Admin → Webhooks → Ver entregas.
2. Localiza la entrega con estado failed o dead.
3. Haz clic en Reintentar.

Alternativamente, usa la API:

curl -X POST https://app.omnibuy.net/api/v1/webhooks/:id/deliveries/:deliveryId/retry \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT"

La entrega se reenvía inmediatamente con el mismo payload y firma originales. El campo id del evento no cambia, así que tu endpoint puede detectar duplicados.