Saltar al contenido principal
Centro de guías4 páginas

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

Guía Define el endpoint, los activadores y la autenticación de entrega de un webhook desde el dashboard o la API.

01 Construir

Eventos y activadores

Referencia Todos los eventos a los que se puede suscribir un webhook, por dominio, y el campo trigger que lo selecciona.

Payloads y ejemplos

Referencia Atributos del payload con JSON de ejemplo para pagos, contracargos, inscripciones, payouts y suscripciones.

Verifica las firmas de webhooks (HMAC)

Guía Valida el encabezado de la firma HMAC SHA256 antes de actuar sobre una entrega.

02 Operar

Entrega y reintentos

Referencia El calendario de reintentos que sigue Yuno cuando tu endpoint no devuelve HTTP 200.

Eliminación de duplicados

Guía La clave de idempotencia por tipo de evento y el código que omite las entregas duplicadas.

Notificaciones de actualización de split

Referencia Cuándo se dispara un evento payment.split_update y qué campos usar para conciliar.

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. Con este calendario predeterminado, Yuno realiza hasta 7 intentos por evento, y el campo 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.
Yuno no reintenta un 404 Not Found. Si la ruta de la URL de tu webhook es incorrecta, o tu framework devuelve 404 para una ruta desconocida, el evento se descarta tras el primer intento. Revisa la URL en Dashboard → Developers → Webhooks y asegúrate de que la ruta devuelva 200.

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 es data.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
Para los eventos subscription.*, la clave identifica la suscripción, no el evento: es el X-Idempotency-Key enviado cuando se creó la suscripción, y se repite idéntica en cada evento del ciclo de vida de esa suscripción. Elimina los duplicados de los eventos subscription.* por type_event más data.idempotency_key; si comparas solo por la clave, todos los eventos de una suscripción se reducen a uno y se pierden en silencio subscription.active, subscription.cancel y el resto.
La compatibilidad con los eventos 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 campo retry 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. Para los payloads v2, guarda la clave específica del evento que procesaste correctamente junto con la cuenta y el type_event del evento, y comprueba los eventos entrantes contra ese almacén antes de actuar sobre ellos:
Ten en cuenta que aún no todos los tipos de evento incluyen una clave de idempotencia (consulta Cobertura más arriba). Para los tipos de evento sin ella, recurre a tu propia clave de eliminación de duplicados, como la combinación del ID del recurso y el tipo de evento.

Configurar un webhook

Los webhooks se configuran de la misma manera tanto si usas el dashboard como la API. Ambos definen la misma url, los mismos activadores y la misma autenticación de entrega.

Configurar un webhook

Configura el endpoint, los activadores y la autenticación de entrega de un webhook, desde el dashboard o la API.

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.
Suscríbete explícitamente a 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.

Qué sigue

Eventos y activadores

El catálogo completo de eventos a los que puedes suscribirte, por dominio.

Payloads y ejemplos

Payloads JSON de ejemplo para cada evento.

Verifica las firmas de webhooks (HMAC)

Confirma que una notificación proviene realmente de Yuno y no fue alterada.

Referencia de la API de webhooks

Todos los campos, endpoints y respuestas de error para gestionar webhooks de forma programática.