Migración de webhooks V1 a webhooks V2


Webhooks V1 será discontinuado

Circle retirará la Versión 1 (V1) de webhooks. La Versión 2 (V2) es el modelo admitido a largo plazo y toda la funcionalidad de webhook se trasladará allí.

 

Qué significa esto para usted:

Si creó sus webhooks recientemente y ya están en V2, no se requiere ninguna acción. 

¿Qué es un webhook?

Un webhook es una forma en que Circle notifica a su aplicación cuando ocurre un evento. En lugar de llamar repetidamente a una API de Circle para verificar actualizaciones, su aplicación registra un endpoint HTTPS. Circle envía una notificación de evento a ese endpoint cuando ocurre un evento compatible, como un cambio en el estado de una transacción.

 

Su aplicación debe autenticar o verificar las notificaciones entrantes, procesar los eventos de manera independiente para que los envíos duplicados no causen acciones duplicadas y devolver una respuesta HTTP exitosa después de aceptar un evento.

¿Por qué existen dos versiones de webhook?

Circle tiene dos generaciones de tecnología de webhook:

 

Las dos versiones utilizan diferentes modelos de entrega, eventos, cargas útiles y verificación de firmas. Debido a estas diferencias, una suscripción V1 no se convierte automáticamente a V2. Las suscripciones V1 existentes continúan enviando eventos durante el período de migración admitido y migrar a V2 es una actualización técnica independiente que usted controla.

Capacidades de V1 y V2

Capacidad

V1

V2

Mantenido a largo plazo

No; retiro programado

Sí

Reintentos automáticos con backoff

No

Sí

Notificaciones firmadas que puede verificar

No

Sí

Identificador de deduplicación incorporado

No

Sí

Recibir eventos en una suscripción existente

Sí, hasta que se retire V1

Sí

 

Qué cambiará cuando actualice su versión

Migrar una integración de V1 a V2 es un cambio técnico, no una configuración. V2 utiliza una estructura de eventos diferente, un modelo de nombres de eventos diferente y un método de verificación de firmas también diferente. Es posible que su integración requiera actualizaciones para:

Revise la documentación para desarrolladores de V2 correspondiente a los productos y tipos de eventos que utiliza antes de cambiar el tráfico de producción.

Enfoque de migración recomendado

Para reducir el riesgo de eventos perdidos o duplicados:

 

  1. Haga un inventario de sus suscripciones de V1 activas, endpoints y lógica de manejo de eventos.
  2. Cree un endpoint separado que admita la estructura de carga útil, tipos de eventos y requisitos de verificación de firmas de V2. Deje su endpoint V1 existente sin cambios.
  3. Cree la suscripción V2 correspondiente y asígnela al nuevo endpoint.
  4. Mantenga activa su suscripción V1 y ejecute V1 y V2 en paralelo mientras valida la entrega y el procesamiento de V2.
  5. Una vez que haya confirmado que V2 funciona como se espera, elimine la suscripción V1 antes de la fecha límite de discontinuación de V1 comunicada.

 

Circle proporcionará un aviso previo antes de deshabilitar la creación de nuevas suscripciones V1 o retirar la entrega existente de V1.