Un webhook es una solicitud HTTP POST que Yuno envía a tu URL en cuanto ocurre un evento, como un pago autorizado, una suscripción renovada o un payout completado, para que tu backend no tenga que consultar de forma periódica. Tu endpoint debe ser una URL HTTPS pública que acepte la solicitud y devuelva HTTP 200, y tú compruebas que cada entrega provino de Yuno con autenticación HMAC u OAuth2.
Empieza aquí: Configurar webhooks
01 Construir
Eventos y activadores
Payloads y ejemplos
Verifica las firmas de webhooks (HMAC)
02 Operar
Entrega y reintentos
Eliminación de duplicados
Notificaciones de actualización de split
API relacionada
Referencia Crear un webhook Listar webhooks Actualizar un webhook
Entrega y reintentos
Yuno espera una respuesta HTTP 200 OK para confirmar que se recibió una notificación. No se requiere cuerpo de respuesta.201 Created y 204 No Content también cuentan como entregado.
Las respuestas de error como 400, 401, 429 y 5xx, un tiempo de espera agotado o un error de conexión inician el calendario de reintentos siguiente, de modo que una interrupción breve de tu lado no hace perder un evento. Cada retraso de reintento se cuenta desde el intento anterior, y el tiempo transcurrido es aproximado y se cuenta desde el primer envío.
retry del payload pasa de 0 en el envío inicial a 6 en el último reintento. Algunas configuraciones de webhook usan un calendario más largo con más reintentos, así que no trates retry: 6 como el intento final.
Eliminación de duplicados
Como Yuno reintenta la entrega cuando no recibe una confirmación, tu endpoint puede recibir el mismo evento más de una vez. Este es un comportamiento esperado, no un error: tu integración debe poder identificar y omitir los duplicados.El identificador
Para los eventos de pago v2 ordinarios, la clave esdata.payment.idempotency_key; para los eventos de suscripción, es data.idempotency_key. Se mantiene estable en cada reintento del mismo evento, así que puedes usarla para distinguir una entrega duplicada de un evento realmente nuevo.
Para payment.split_update, usa en su lugar data.split_update.idempotency_key: identifica la operación de actualización de split. El data.payment.idempotency_key existente del pago puede ser compartido por varias actualizaciones de split distintas. Define el alcance de tu registro de eliminación de duplicados por cuenta, tipo de evento y clave de la operación. En los payloads v1 heredados, usa el split_update.idempotency_key de nivel superior.
Cobertura
La ubicación de la clave depende del evento:- Eventos de pago ordinarios, incluidos reembolso y contracargo:
data.payment.idempotency_key - Eventos de actualización de split:
data.split_update.idempotency_key - Eventos de suscripción:
data.idempotency_key
enrollment está prevista, pero aún no está disponible. Hasta entonces, los payloads de inscripción no incluyen data.idempotency_key.Por qué puedes ver el mismo evento dos veces
Cada payload v2 también incluye un camporetry de nivel superior con el número de intentos de entrega realizados para ese evento (0 en el primer intento). Si tu endpoint no devuelve un HTTP 200 OK a tiempo, Yuno vuelve a enviar el mismo evento (la misma clave de idempotencia específica del evento, con retry incrementado) siguiendo el calendario descrito en Entrega y reintentos más arriba. Trata como duplicado cualquier evento cuyo type_event y clave de idempotencia ya hayas procesado, sin importar su valor de retry.
Manejo recomendado
Para los payloads v2, guarda la clave específica del evento que procesaste correctamente junto con la cuenta y eltype_event del evento, y comprueba los eventos entrantes contra ese almacén antes de actuar sobre ellos:
Configurar un webhook
Los webhooks se configuran de la misma manera tanto si usas el dashboard como la API. Ambos definen la mismaurl, los mismos activadores y la misma autenticación de entrega.
Configurar un webhook
Notificaciones de actualización de split
payment.split_update requiere que el activador de actualización de split esté disponible en el catálogo de webhooks de tu cuenta. La disponibilidad de la suscripción en producción está pendiente; este evento no se habilita mediante una suscripción de compra o de reembolso.SPLIT_UPDATE en payment_triggers cuando el catálogo lo ponga a disposición. Las suscripciones PURCHASE y REFUND existentes y sus payloads no cambian.
Se inicia una notificación después de que la actualización de split se registra como aplicada. También se inicia después de que una resolución manual confirma APPLY_REQUESTED (aplicar el split solicitado) o SET_EMPTY (borrar el split). KEEP_PREVIOUS, las actualizaciones fallidas o sin resolver, las repeticiones de solicitud con la misma clave y las resoluciones repetidas no inician otra notificación.
El payload incluye split_update.idempotency_key, la clave de la solicitud original de actualización de split, y split_update.updated_at, la marca de tiempo registrada de finalización de esa operación. Esta marca de tiempo no es la hora de envío del webhook ni la hora de la última actualización general del pago. Consulta los ejemplos v1 y v2.
El payment.transactions.split_marketplace del evento es el split registrado para esa operación. Sigue siendo el split de esa operación aunque una actualización posterior se complete antes de la entrega. Los demás campos del pago se leen cuando se prepara la notificación, por lo que el cuerpo no es una instantánea histórica completa del pago. Para obtener el estado más reciente, consulta el pago con GET /v1/payments/{payment_id}. No sobrescribas un split más reciente con un evento más antiguo; usa la marca de tiempo de la operación al conciliar y consulta el pago cuando el orden sea ambiguo.
La entrega no es exactamente una vez y los eventos pueden llegar fuera de orden. La actualización de split puede completarse correctamente aunque falle el envío de la notificación. Una vez que se acepta una notificación para su entrega por webhook, los reintentos normales de webhook pueden producir entregas duplicadas. Elimina los duplicados por la clave de la operación de split, confirma la recepción y consulta el pago cuando necesites su estado actual.