Webhooks

Los webhooks de v2 permiten que tu ERP reciba notificaciones cuando ocurren cambios operativos — órdenes, pagos, sync jobs completados, actualizaciones de catálogo y más.

En lugar de hacer polling a la API, registrás un endpoint y OrderFast te envía los eventos automáticamente.

Cómo funciona

1. Registrás un webhook endpoint con tu URL y los eventos que necesitás.
2. OrderFast envía un POST a tu URL cuando ocurre un evento suscripto.
3. Tu servidor valida la firma, procesa el evento y responde 2xx.
4. Si falla, OrderFast reintenta según la política de reintentos.

Referencia interactiva

Explorá los endpoints de Webhooks con ejemplos cURL en la referencia API.

Registrar un webhook endpoint

POST /v2/webhook-endpoints
Idempotency-Key: webhook-setup-001

Request:

{
  "url": "https://tu-erp.com/webhooks/orderfast",
  "events": [
    "order.created",
    "sync.completed",
    "catalog.updated"
  ]
}

Response:

{
  "data": {
    "id": "wh_001",
    "url": "https://tu-erp.com/webhooks/orderfast",
    "events": ["order.created", "sync.completed", "catalog.updated"],
    "status": "active",
    "created_at": "2026-07-01T10:00:00.000Z",
    "secret": "whsec_abc123..."
  }
}

Guardá el secret

El campo secret se devuelve solo al crear el endpoint. Guardalo de forma segura — lo necesitás para verificar la firma de cada evento entrante.

Idempotencia

La creación de webhook endpoints requiere el header Idempotency-Key. Si reintentás con la misma key y el mismo body, recibirás la misma respuesta sin crear un duplicado.

Endpoints de gestión

Método	Endpoint	Descripción
GET	/v2/webhook-endpoints	Listar endpoints registrados
POST	/v2/webhook-endpoints	Crear un nuevo endpoint
PATCH	/v2/webhook-endpoints/:id	Actualizar URL, eventos o estado
DELETE	/v2/webhook-endpoints/:id	Eliminar un endpoint
POST	/v2/webhook-endpoints/:id/test	Enviar un evento de prueba
GET	/v2/webhook-endpoints/:id/deliveries	Ver historial de entregas

Probar tu endpoint

POST /v2/webhook-endpoints/:id/test

Envía un evento de prueba para verificar que tu ERP recibe, valida y responde correctamente.

Consultar entregas

GET /v2/webhook-endpoints/:id/deliveries

Devuelve el historial de intentos con estado, número de intento y código de respuesta HTTP.

Eventos disponibles

Categoría	Eventos
Órdenes	order.created, order.updated, order.cancelled, order.completed, order.status_changed
Pagos	payment.created, payment.updated, payment.completed, payment.rejected
Catálogo	product.created, product.updated, product.deleted, stock.updated, catalog.updated
Sync	sync.completed, sync.failed
Operaciones	turn.closed, settlement.created

Suscribite solo a los eventos que tu ERP necesita. Ver payloads de cada evento.

Requisitos de tu endpoint

Tu servidor debe:

• Aceptar requests POST con Content-Type: application/json
• Responder con un código 2xx en menos de 30 segundos
• Verificar la firma HMAC de cada evento
• Ser idempotente — el mismo evento puede llegar más de una vez por reintentos
• Procesar eventos de forma asíncrona si la lógica de conciliación es pesada

Casos de uso típicos en ERP

Evento	Acción en tu ERP
order.created	Registrar la venta en el sistema contable
order.status_changed	Actualizar el estado del pedido en tu ERP
sync.completed	Confirmar que el sync batch terminó y revisar ítems fallidos
sync.failed	Alertar al operador y reintentar la sincronización
catalog.updated	Invalidar cache de catálogo local
settlement.created	Registrar el cierre de conciliación financiera

Relacionado

• Eventos — estructura y ejemplos de payloads
• Firma HMAC — cómo validar que el evento viene de OrderFast
• Reintentos — qué pasa si tu endpoint falla