Versiones y compatibilidad

Lo publicado solo crece. Añadir es compatible: lo hacemos sin cambiar de versión y sin avisar antes. Por eso tu integración debe ignorar lo que no conozca — campos, tipos de evento y valores nuevos — y tratar cada lista cerrada de valores con un caso por defecto.

Quitar o renombrar algo, cambiar su tipo o su significado, o empezar a exigir algo que hoy es opcional sería un cambio incompatible. Nunca lo hacemos sobre lo que ya está publicado:

• publicamos una versión nueva junto a la actual;
• mantenemos las dos durante al menos 6 meses;
• lo anunciamos en Cambios y por email a los administradores de las organizaciones afectadas, con la fecha en que la versión anterior dejará de funcionar.

Cada cambio, compatible o no, queda en Cambios, marcado como «Compatible» o «Incompatible». Puedes seguirlo con su feed Atom.

Cada entrega de un webhook de eventos lleva tres marcas de versión, independientes entre sí:

• specversion: la versión del formato CloudEvents del cuerpo. Siempre 1.0.
• v1, al principio de cada firma de webhook-signature: la versión del esquema de firma. Ver la firma.
• type y dataschema: la versión de los datos. call.ended es la versión 1 de ese tipo, y su dataschema es https://calligence.ai/docs/webhooks/schemas/call.ended/v1.json. Una versión 2 se llamaría call.ended.v2 y su esquema acabaría en /v2.json.

Los esquemas son JSON Schema (2020-12) y describen data: sirven para validar lo que recibes o para generar tipos en tu lenguaje. Son abiertos: aceptan campos y valores que todavía no listan, así que validar con ellos no falla cuando el contrato crece. Cada tipo del catálogo enlaza el suyo.

Una versión publicada solo crece. Sin cambiar de versión y sin avisar antes, podemos:

• añadir campos a data o a sus objetos;
• añadir valores a un vocabulario cerrado;
• añadir tipos al catálogo (solo los recibes si te suscribes a ellos);
• añadir atributos al cuerpo del evento.

Cada tipo nuevo queda en Cambios; los campos y valores nuevos aparecen en el catálogo y en el esquema de su versión, que se actualiza en la misma URL.

Quitar o renombrar un campo, cambiar su tipo o su significado, o quitar un valor de un vocabulario rompería a quien ya recibe ese tipo. Nunca lo hacemos sobre una versión publicada: publicamos un tipo nuevo, <tipo>.v2, con su propio esquema.

• Durante al menos 6 meses enviamos los dos: cada webhook sigue recibiendo los tipos a los que está suscrito.
• Lo anunciamos en Cambios y por email a los administradores de las organizaciones con algún webhook suscrito al tipo antiguo, con la fecha en que dejará de enviarse.
• Para migrar, suscribe tu webhook también al tipo nuevo, adapta tu receptor y quita el antiguo.

Los resultados que la conexión Webhook envía a tu endpoint llevan su versión en la clave version: hoy, 1. La firma lleva la suya: el v1 de la cabecera X-Calligence-Signature.

Compatible, sin avisar: añadir claves al objeto (como todas, siempre presentes y con null cuando no apliquen), añadir valores de event o de status y etiquetas nuevas. Si tu endpoint recibe un event que no conoce, que conteste 2xx y lo ignore.

Incompatible: quitar o renombrar una clave, cambiar su tipo o su significado, o cambiar la firma. Llegaría como version: 2, que eliges para cada conexión cuando estés listo: hasta entonces te seguimos enviando la versión 1, durante al menos 6 meses desde el anuncio.

En GoHighLevel y Zoho CRM escribimos textos fijos de los que pueden depender tus workflows: la cabecera de la nota (Calligence — resumen de la llamada:), la etiqueta con el resultado final (Calligence: …, por ejemplo Calligence: Éxito) y el título de la cita (Cita Calligence — {nombre}, o solo Cita Calligence si no sabemos el nombre). Cada guía los describe: GoHighLevel y Zoho CRM.

Compatible, sin avisar: etiquetas nuevas para resultados nuevos y notas con más información.

Incompatible: cambiar el texto de una etiqueta, de la cabecera de la nota o del título de la cita que ya escribimos. Si alguna vez hiciera falta, te avisaríamos con al menos 6 meses de antelación y, mientras tanto, seguiríamos escribiendo el texto actual.

Las peticiones con las que nos envías leads — a la URL de tu campaña, desde la conexión Webhook o desde los workflows de GoHighLevel y Zoho — no llevan número de versión: crecen sin romper lo que ya funciona.

Compatible, sin avisar: aceptar claves o formatos que hoy no reconocemos, y añadir claves a nuestras respuestas.

Incompatible: exigir un campo que hoy es opcional, rechazar una petición que hoy aceptamos, cambiar el significado de un campo o el código con el que respondemos a una misma petición. Si alguna vez hiciera falta, publicaríamos la forma nueva junto a la actual — por ejemplo, en otra URL — y aceptaríamos las dos durante al menos 6 meses.

• Cambios lista cada cambio, el más reciente primero, con su fecha, a qué afecta y si es compatible.
• Su feed Atom te lo lleva a tu lector de feeds.
• Antes de un cambio incompatible, escribimos a los administradores de cada organización afectada, con la fecha en que la versión anterior dejará de funcionar.