Webhooks

Un webhook es un aviso: en vez de que tu sistema pregunte cada rato si pasó algo, ODECIS le manda una petición HTTP en el momento en que pasa.

Dos cosas que conviene saber antes de empezar: los avisos son instantáneos, y si tu servidor no responde reintentamos hasta 6 veces.

Eventos disponibles

Productos

Evento	Cuándo se dispara
product.created	Se creó un producto
product.updated	Se actualizó un producto
product.deleted	Se eliminó un producto

Inventario

Evento	Cuándo se dispara
stock.changed	Cambió el stock de un producto

Ventas

Evento	Cuándo se dispara
order.created	Se creó una orden de venta
order.status_changed	Cambió el estado de una orden
order.cancelled	Se anuló una orden

Facturación

Evento	Cuándo se dispara
invoice.created	Se emitió un comprobante electrónico
invoice.cancelled	Se anuló un comprobante

Formato del payload

{
  "event": "product.created",
  "timestamp": "2025-12-12T15:30:00.000Z",
  "webhookId": "wh_abc123xyz",
  "data": {
    "product": {
      "id": "prod_123",
      "sku": "LAP-HP-001",
      "name": "Laptop HP ProBook",
      "price": 2499.90,
      "stock": 25,
      "createdAt": "2025-12-12T15:30:00.000Z"
    }
  }
}

Política de reintentos

Si tu servidor no responde, reintentamos con espera creciente:

Intento	Espera
1	Inmediato
2	1 minuto
3	5 minutos
4	15 minutos
5	1 hora
6	2 horas

Mejores prácticas

• Responde rápido. Devuelve 200 OK de inmediato y procesa después. Si tardas, el aviso se cuenta como fallido y entra a la cola de reintentos.
• Usa HTTPS. Solo aceptamos endpoints con SSL válido.
• Verifica la firma. Valida siempre el encabezado X-Webhook-Signature antes de confiar en el contenido.
• No confíes en el orden. Los webhooks pueden llegar desordenados: usa el timestamp del payload, no el orden de llegada.