Webhooks

Los webhooks permiten que Cost+ notifique a tu servidor en tiempo real cada vez que cambia el estado de un pedido. En lugar de hacer polling a la API, proporcionas una URL y Cost+ envia una solicitud HTTP POST cada vez que hay una actualizacion.

Como funcionan los webhooks

Especificas una webhook_url al crear un pedido, o configuras una URL de webhook predeterminada a nivel de proyecto.
Cuando cambia el estado del pedido (ej., de new a completed), Cost+ envia una solicitud POST a tu URL de webhook.
Tu servidor recibe el webhook y luego llama a la API de Cost+ para obtener los detalles completos del pedido.
Actualizas tu sistema basandote en el estado verificado del pedido.

Nunca confies unicamente en el payload del webhook para procesar un pedido. Verifica siempre el estado del pedido realizando una solicitud GET /v1/orders/{id}/ despues de recibir un webhook. El webhook es un mecanismo de notificacion, no una fuente de verdad.

Payload del webhook

El cuerpo del webhook es un objeto JSON que contiene el tipo de evento y el ID del pedido:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Campo	Descripcion
`event`	El tipo de evento. Actualmente `status_changed` para actualizaciones de pedidos.
`order_id`	El identificador unico del pedido cuyo estado cambio.
`project_id`	El proyecto al que pertenece el pedido.

Configurar la URL del webhook

Puedes configurar la URL del webhook de dos formas:

Por pedido

Incluye el campo webhook_url al crear un pedido:

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Predeterminado del proyecto

Configura una URL de webhook predeterminada en tu panel de Cost+ en la configuracion del proyecto. Esta URL se usara para todos los pedidos que no especifiquen su propia webhook_url.

Aunque tengas un valor predeterminado a nivel de proyecto, puedes sobreescribirlo por pedido incluyendo webhook_url en la solicitud de creacion del pedido.

Logica de reintentos

Si tu servidor no responde con un codigo de estado 2xx, Cost+ reintenta la entrega del webhook:

Reintentos maximos: 10 intentos
Intervalo entre reintentos: 2 minutos entre cada intento
Timeout del primer intento: 4 segundos
Timeout de intentos posteriores: 10 segundos

Si los 10 intentos de reintento fallan, el webhook se marca como fallido. Aun puedes consultar el estado del pedido en cualquier momento haciendo polling a la API.

Asegurate de que tu endpoint de webhook responda rapidamente (dentro de 4 segundos para el primer intento). Realiza cualquier procesamiento de larga duracion de forma asincrona despues de devolver una respuesta 200 OK.

Mejores practicas

Verifica siempre a traves de la API. Al recibir un webhook, llama a GET /v1/orders/\{order_id\}/ para confirmar el estado actual antes de tomar acciones como enviar productos o conceder acceso.
Devuelve 200 rapidamente. Confirma la recepcion del webhook con una respuesta 200 de inmediato y procesa el pedido de forma asincrona para evitar timeouts.
Gestiona duplicados. Tu endpoint de webhook puede recibir el mismo evento mas de una vez. Asegurate de que tu logica de procesamiento sea idempotente.
Usa HTTPS. Utiliza siempre una URL HTTPS para tu endpoint de webhook para garantizar que el payload se transmita de forma segura.
Registra los payloads de webhook. Almacena los datos de webhook entrantes para depuracion y auditoria.

Endpoints relacionados

Crear pedido — establecer la webhook_url por pedido
Actualizar pedido — actualizar la URL del webhook en un pedido existente
Esquemas de eventos de webhook — formato del payload para OrderStatusChangedEvent y TransactionStatusChangedEvent

On this page