Webhooks

Los webhooks permiten que tu sistema reciba notificaciones HTTP cuando algo importante ocurre en OrderFast — una orden creada, un pago completado, un cambio de stock, etc.

En lugar de consultar la API en loop, registrás una URL y OrderFast te envía el evento automáticamente.

Cómo funciona

1. Registrás un endpoint con la URL de tu servidor y los eventos que querés recibir.
2. OrderFast envía un POST a tu URL cada vez que 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

POST /v1/webhooks

Request:

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

Response:

{
  "data": {
    "id": "wh_001",
    "url": "https://tu-servidor.com/webhooks/orderfast",
    "events": ["order.created", "order.updated", "payment.completed"],
    "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 webhook. Guardalo de forma segura — lo necesitás para verificar la firma de cada evento entrante.

Endpoints de gestión

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

Probar tu endpoint

POST /v1/webhooks/:id/test

Envía un evento de prueba a tu URL para verificar que tu servidor recibe, valida y responde correctamente antes de ir a producción.

Consultar entregas

GET /v1/webhooks/:id/deliveries

Devuelve el historial de intentos de entrega con estado, número de intento y código de respuesta HTTP. Útil para diagnosticar fallos.

Eventos disponibles

Categoría	Eventos
Órdenes	order.created, order.updated, order.cancelled, order.completed
Pagos	payment.created, payment.updated, payment.completed, payment.rejected
Catálogo	product.created, product.updated, product.deleted, stock.updated
Turnos	turn.open, turn.updated, turn.closed

Suscribite solo a los eventos que tu integración 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

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