Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real cuando ocurren eventos en tu tienda, sin necesidad de hacer polling.

Formato de evento (CloudEvents v1.0)

{
  "specversion": "1.0",
  "id": "01J...",
  "source": "/omnibuy/orders",
  "type": "orders.order.created",
  "time": "2026-04-08T12:00:00Z",
  "datacontenttype": "application/json",
  "tenantid": "<tenant-uuid>",
  "data": { ... }
}

Registrar un webhook

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://mi-app.com/webhooks/omnibuy",
    "events": ["orders.order.created", "payments.payment.captured"],
    "secret": "mi_secreto_hmac_256"
  }'

Estructura del payload

Cada evento sigue el envelope de CloudEvents v1.0. El campo data contiene el objeto real del recurso afectado:

{
  "specversion": "1.0",
  "id": "01JABC123...",
  "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",
    "items": [
      { "sku": "PROD-001", "qty": 2, "price": 7995 }
    ],
    "created_at": "2026-04-08T12:00:00Z"
  }
}

Los campos comunes a todos los eventos:

Campo	Descripción
specversion	Siempre "1.0"
id	UUID único del evento (idempotencia)
source	Ruta del recurso origen
type	Nombre del evento (p.ej. orders.order.created)
time	Timestamp ISO 8601 en UTC
tenantid	UUID del tenant
data	Payload específico del evento

Comportamiento de entrega

• Timeout: cada intento tiene un límite de 5 segundos. Si tu endpoint no responde dentro de ese plazo, se marca como fallo.
• Reintentos: ante un fallo (timeout o status HTTP ≠ 2xx), OmniBuy reintenta con backoff exponencial:

Intento	Espera
1 → 2	1 min
2 → 3	5 min
3 → 4	30 min
4 → 5	2 horas

Después de 5 intentos fallidos, la entrega se marca como dead. Puedes reintentar manualmente desde el panel de administración.

• Idempotencia: el campo id es único por evento. Tu endpoint debe manejar entregas duplicadas de forma segura.

Verificación de firma

Cada entrega incluye el header X-OmniBuy-Signature con un HMAC-SHA256 del body firmado con tu secret. Siempre verifica esta firma antes de procesar el payload.

Para más detalles sobre seguridad, ver Seguridad de webhooks.

func verify(body []byte, sig, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(sig))
}

Endpoints de gestión

• GET /api/v1/webhooks — listar
• POST /api/v1/webhooks — crear
• DELETE /api/v1/webhooks/:id — eliminar
• GET /api/v1/webhooks/:id/deliveries — historial de entregas
• POST /api/v1/webhooks/:id/deliveries/:deliveryId/retry — reintentar entrega