Saltar al contenido principal

Migrar al formato firmado

Los webhooks del formato anterior siguen funcionando sin cambios. Cuando quieras usar firmas, reintentos automáticos y los eventos de disputas, reembolsos y liquidaciones, creá un reemplazo desde el Dashboard. Tu webhook actual sigue recibiendo eventos hasta que actives el reemplazo, y durante 72 horas podés volver atrás.

Qué cambia​

Formato anteriorFormato firmado
AutenticaciónEl header X-Webhook-Secret lleva el secreto.El header X-Onvo-Signature lleva una firma con marca de tiempo; el secreto nunca viaja. Ver Verificar firmas.
Cuerpo{ "type", "data" } con el objeto completo.Un sobre con id, type y data.object, que contiene solo los campos públicos.
Nombres de eventoCon guiones: payment-intent.succeeded.Con guion bajo: payment_intent.succeeded.
ReintentosUn solo intento, sin reintentos.Reintentos automáticos: hasta 72 horas en producción.
EventosPagos, renovaciones, programaciones de cargos recurrentes, Checkout y transferencias.Además, disputas, reembolsos y liquidaciones.
SelecciónRecibe todos los eventos.Recibe solo los eventos que seleccionás.

Equivalencias de nombres:

Formato anteriorFormato firmado
payment-intent.succeededpayment_intent.succeeded
payment-intent.failedpayment_intent.failed
payment-intent.deferredpayment_intent.processing
subscription.renewal.succeededsubscription_renewal.succeeded
subscription.renewal.failedsubscription_renewal.failed
subscription-schedule.createdsubscription_schedule.created
subscription-schedule.updatedsubscription_schedule.updated
subscription-schedule.activatedsubscription_schedule.activated
subscription-schedule.canceledsubscription_schedule.canceled
subscription-schedule.releasedsubscription_schedule.released
subscription-schedule.completedsubscription_schedule.completed
subscription-schedule.phase-transitionedsubscription_schedule.phase_transitioned
subscription-schedule.transition-failedsubscription_schedule.transition_failed
checkout-session.succeededcheckout_session.succeeded
mobile-transfer.receivedmobile_transfer.received

Los objetos también cambian. Por ejemplo, una intención de pago trae customerId y latestCharge en lugar del cliente completo y la lista de cargos. Si necesitás más datos, consultalos en la API con el ID del objeto.

Pasos​

  1. En Desarrolladores > Webhooks, buscá tu webhook en Integraciones existentes y elegí Actualización disponible.
  2. Revisá el nombre, la URL y los eventos del reemplazo. El Dashboard muestra cuántos eventos recibió tu webhook en los últimos días y avisa si alguno no tiene equivalente en el formato firmado.
  3. Elegí Crear reemplazo desactivado y guardá el nuevo secreto de firma (whsec_...). Tu webhook actual sigue activo.
  4. Actualizá tu servidor para que verifique la firma y lea el nuevo sobre y los nuevos nombres de evento. Mientras dure la migración, podés distinguir el formato por el header: las peticiones firmadas traen X-Onvo-Signature y las anteriores, X-Webhook-Secret.
  5. Elegí Probar conexión. La prueba exitosa vale 24 horas. Se invalida si cambiás la URL, si rotás el secreto de firma o si una prueba posterior falla.
  6. Marcá Verifiqué la nueva firma en mi receptor y elegí Activar reemplazo. ONVO activa el reemplazo y desactiva el webhook anterior al mismo tiempo.

Cada evento se envía en el formato que estaba activo cuando ocurrió, nunca en los dos: un evento que ocurrió justo antes de la activación todavía puede llegar en el formato anterior después del cambio. La excepción es mobile_transfer.received, que puede llegar en los dos formatos si la transferencia se recibe justo durante la activación. Los dos formatos no comparten el ID del evento, así que descartá duplicados con el ID del objeto. ONVO no vuelve a enviar en el formato nuevo los eventos que ya se entregaron en el anterior.

Volver al webhook anterior​

Durante las 72 horas siguientes a la activación, podés elegir Restaurar endpoint anterior: el webhook anterior vuelve a recibir los eventos nuevos y el reemplazo vuelve a ser un borrador. Para usarlo otra vez, necesita una prueba de conexión exitosa de las últimas 24 horas, la confirmación de que verificaste la firma y Activar reemplazo. Los eventos ocurridos mientras estaba activo el otro formato no se reenvían.

Si todavía no activaste el reemplazo, podés Descartar borrador sin afectar tu webhook actual.

Eliminar o reactivar el webhook anterior​

ONVO evita que tu servidor reciba cada evento en los dos formatos:

  • No podés reactivar el webhook anterior mientras su reemplazo está activo. Para volver atrás, usá Restaurar endpoint anterior dentro de las 72 horas, o desactivá primero el reemplazo.
  • No podés restaurar el webhook anterior mientras otro endpoint activo usa su URL. Desactivá primero ese endpoint.
  • No podés reactivar un webhook del formato anterior, ni cambiar la URL de uno activo, mientras un endpoint firmado activo usa esa URL.
  • No podés activar un endpoint mientras el webhook que reemplazó está activo, ni mientras otro webhook activo del formato anterior usa su URL. Desactivá primero ese webhook.
  • No podés crear ni editar un endpoint para que use la URL de un webhook activo del formato anterior: usá Actualización disponible en ese webhook.

Si eliminás el webhook anterior, ONVO descarta su borrador de actualización y revoca el secreto del borrador. Si el reemplazo ya está activo, sigue funcionando, pero ya no podés restaurar el webhook anterior. Los registros del webhook anterior también se eliminan.