Webhooks y recuperación

Configurar un destino

Un administrador abre una clave en API & integrations y añade un destino HTTP o HTTPS. Se recomienda HTTPS; la interfaz avisa cuando se usa HTTP, una dirección IP directa o una dirección local, sin impedir el registro. El middleware debe poder acceder a la URL para entregar los eventos. El destino pertenece a esa clave y tiene su propio secreto de firma, que solo se muestra al crearlo o renovarlo. Selecciona tipos de evento si el receptor solo necesita parte del flujo. Sustituir o revocar la clave también afecta a sus destinos; prepara el receptor antes de activarlos.

Verificar antes de procesar

Cada envío incluye webhook-id, webhook-timestamp y webhook-signature. La firma sigue Standard Webhooks: HMAC-SHA256 sobre los bytes UTF-8 de webhook-id + "." + webhook-timestamp + ".", seguidos de los bytes exactos del cuerpo sin procesar. El secreto empieza por whsec_; lo que sigue es una clave de firma codificada en Base64. Compara la firma Base64 de una entrada v1, en tiempo constante.

Rechaza las marcas de tiempo que difieran más de cinco minutos de la hora de tu servidor. Verifica la firma antes de analizar el JSON. Comprueba después que el id del evento coincide con webhook-id y registra ese identificador antes de aplicar efectos de negocio. Responde rápidamente con un 2xx para confirmar la recepción.

Los envíos pueden repetirse y llegar fuera de orden. Deduplica por identificador de evento. Un evento de validación contiene identificadores y rutas API; recupera el informe o expediente actual con la API autenticada si necesitas todos los datos. Los eventos de validación son rental.departure.completed y rental.return.completed. Las correcciones y la disponibilidad del PDF tienen eventos propios. La definición OpenAPI del webhook de Alquiler describe todos los tipos y campos.

Recuperar eventos perdidos

Usa GET /v1/events con su cursor y, si procede, created_after después de una interrupción. Los eventos se conservan 30 días. Avanza el cursor guardado solo cuando hayas procesado la página recibida. La plataforma reintenta los envíos fallidos hasta ocho veces durante 48 horas; un administrador puede consultar y reintentar fallos recientes en API & integrations.

Considera el flujo como una notificación y las rutas autenticadas como fuente de los datos actuales. Informes y pruebas explica cómo archivarlos.