Funcionamiento
Versiones
Qué significa v1 en la ruta y api_version en cada evento, y en qué estado está hoy el contrato.
La API tiene dos marcas de versión, y cada una dice una cosa distinta.
v1 en la ruta
Todas las rutas van bajo /v1. Es la versión mayor del contrato: las rutas, los objetos y su significado.
api_version en cada evento
Cada evento lleva api_version: "2026-09-24", y el User-Agent de los webhooks lo repite (SafeOnuba-Webhooks/2026-09-24). Es la fecha de la versión del formato con el que se ha generado ese evento.
Guárdala junto a cada evento que recibas. Si algún día conviven formatos, es lo que te dirá con cuál se escribió cada uno.
Estado actual: vista previa
Mientras dure la vista previa:
- Genera tu cliente, si lo haces, desde el contrato (OpenAPI 3.1) y vuelve a generarlo cuando cambie.
- Ignora los campos que no conozcas en lugar de fallar. Es la forma más sencilla de que un campo nuevo no rompa tu integración.
- Programa contra el
codede los errores y contra los valores de los enums, no contra textos.
El contrato
El contrato OpenAPI 3.1 es la fuente de verdad: la referencia de esta documentación se genera desde él en cada despliegue. Lo tienes para descargar en /desarrolladores/openapi.json, y la API lo sirve en GET /v1/openapi.json, sin token.