Saltar al contenido principal
POST
Crear un webhook
Crea un webhook en estado ACTIVE, por lo que empieza a recibir notificaciones de inmediato. Envía la url de destino, un name que sea único dentro de la cuenta y al menos un trigger. La respuesta incluye el id que usas para consultarlo, actualizarlo y eliminarlo. Para proteger cómo Yuno llama a tu endpoint, agrega al mismo cuerpo los campos de cualquier método de autenticación de la entrega. Son opcionales y puedes combinarlos. Los secretos que configures se devuelven enmascarados, y el resto se devuelve como null.
Para definir oauth2_scope, usa Actualizar un webhook.
Una cuenta puede tener varios webhooks que apunten a la misma url, siempre que escuchen eventos distintos. Un webhook se rechaza con 409 WEBHOOK_ALREADY_EXISTS cuando la cuenta ya tiene uno con el mismo name, o uno con la misma url que escucha alguno de los mismos eventos.

Autorizaciones

public-api-key
string
header
predeterminado:<Your public-api-key>
requerido
private-secret-key
string
header
predeterminado:<Your private-secret-key>
requerido

Cuerpo

application/json
account_id
string<uuid>
requerido

El identificador único de la cuenta a la que pertenece el webhook.

Ejemplo:

"493e9374-510a-4201-9e09-de669d75f256"

name
string
requerido

Tu nombre para el webhook. Debe ser único dentro de la cuenta.

Ejemplo:

"Production payments listener"

url
string
requerido

El endpoint al que Yuno envía las notificaciones. Debe ser una URL http o https que se resuelva a una dirección pública y enrutable.

Ejemplo:

"https://api.acme.com/yuno/webhooks"

api_key
string

Se envía a tu endpoint como el encabezado x-api-key en cada entrega.

Ejemplo:

"my-webhook-key"

secret
string

Se envía a tu endpoint como el encabezado x-secret en cada entrega.

Ejemplo:

"my-webhook-secret"

hmac_client_secret
string

La clave con la que Yuno firma el payload. La firma viaja en el encabezado x-hmac-signature.

Ejemplo:

"my-hmac-secret"

oauth2_authentication_url
string

Tu endpoint de token. Debe usar HTTPS. Envía oauth2_authentication_url, oauth2_client_id, oauth2_client_secret y oauth2_grant_type juntos.

Ejemplo:

"https://api.acme.com/oauth/token"

oauth2_client_id
string

El identificador de cliente con el que Yuno se autentica. Envía oauth2_authentication_url, oauth2_client_id, oauth2_client_secret y oauth2_grant_type juntos.

Ejemplo:

"acme_client_id"

oauth2_client_secret
string

El secreto de cliente con el que Yuno se autentica. Envía oauth2_authentication_url, oauth2_client_id, oauth2_client_secret y oauth2_grant_type juntos.

Ejemplo:

"acme_client_secret"

oauth2_grant_type
string

El tipo de concesión con el que Yuno solicita el token. Envía oauth2_authentication_url, oauth2_client_id, oauth2_client_secret y oauth2_grant_type juntos.

Ejemplo:

"client_credentials"

oauth2_authorization_name
string

El encabezado en el que Yuno envía el token. Por defecto es Authorization.

Ejemplo:

"Authorization"

oauth2_include_client_id
boolean

Envía también el identificador de cliente como encabezado en la solicitud del token.

Ejemplo:

false

enrollment_triggers
enum<string>[]

Los eventos de inscripción a los que se suscribe el webhook.

Opciones disponibles:
ENROLL,
UNENROLL
Ejemplo:
payment_triggers
enum<string>[]

Los eventos de pago a los que se suscribe el webhook.

Opciones disponibles:
AUTHORIZE,
CANCEL,
CAPTURE,
CHARGEBACK,
PRECHARGEBACK,
PURCHASE,
REFUND,
SPLIT_UPDATE,
VERIFY
Ejemplo:
report_triggers
enum<string>[]

Los eventos de reportes a los que se suscribe el webhook.

Opciones disponibles:
CREATE,
UPDATE
Ejemplo:
subscription_triggers
enum<string>[]

Los eventos de suscripción a los que se suscribe el webhook.

Opciones disponibles:
ACTIVE,
CANCEL,
CLOSE_TO_RENEWAL,
COMPLETE,
CREATE,
CREATION_FAILED,
PAUSE,
PLAN_CHANGE_CANCELED,
PLAN_CHANGE_SCHEDULED,
PLAN_CHANGED,
PROMOTION_APPLIED,
RESUME
Ejemplo:
onboarding_triggers
enum<string>[]

Los eventos de onboarding a los que se suscribe el webhook.

Opciones disponibles:
BLOCKED,
CANCELLED,
CREATED,
DECLINED,
ERROR,
EXPIRED,
INACTIVE,
PENDING,
SUCCEEDED,
TRANSFERRED,
UNBLOCKED
Ejemplo:
renewal_days
integer

Cuántos días antes de una renovación Yuno envía la notificación CLOSE_TO_RENEWAL. Debe ser 1 o más, y solo es válido cuando subscription_triggers contiene CLOSE_TO_RENEWAL.

Ejemplo:

5

Respuesta

El webhook que creaste. Los secretos que configuraste se devuelven enmascarados, y los que omitiste se devuelven como null.

id
string

El identificador único del webhook.

Ejemplo:

"12345"

account_id
string<uuid>

El identificador único de la cuenta a la que pertenece el webhook.

Ejemplo:

"493e9374-510a-4201-9e09-de669d75f256"

name
string

Tu nombre para el webhook.

Ejemplo:

"Production payments listener"

state
enum<string>

Los webhooks ACTIVE reciben notificaciones, los INACTIVE no. Un webhook empieza como ACTIVE.

Opciones disponibles:
ACTIVE,
INACTIVE
Ejemplo:

"ACTIVE"

url
string

El endpoint al que Yuno envía las notificaciones.

Ejemplo:

"https://api.acme.com/yuno/webhooks"

api_key
string | null

Enmascarado como ***, o null cuando no lo has configurado.

Ejemplo:

"***"

secret
string | null

Enmascarado como ***, o null cuando no lo has configurado.

Ejemplo:

"***"

hmac_client_secret
string | null

Enmascarado como ***, o null cuando no lo has configurado.

Ejemplo:

"***"

oauth2_authentication_url
string | null

Tu endpoint de token.

Ejemplo:

"https://api.acme.com/oauth/token"

oauth2_client_secret
string | null

Enmascarado como ***, o null cuando no lo has configurado.

Ejemplo:

"***"

oauth2_client_id
string | null

El identificador de cliente con el que Yuno se autentica.

Ejemplo:

"acme_client_id"

oauth2_grant_type
string | null

El tipo de concesión con el que Yuno solicita el token.

Ejemplo:

"client_credentials"

oauth2_scope
string | null

El alcance con el que Yuno solicita el token.

Ejemplo:

"webhooks:write"

oauth2_authorization_name
string | null

El encabezado en el que Yuno envía el token.

Ejemplo:

"Authorization"

oauth2_include_client_id
boolean

Indica si Yuno también envía el identificador de cliente como encabezado en la solicitud del token.

Ejemplo:

true

enrollment_triggers
string[] | null

Los eventos de inscripción a los que se suscribe el webhook.

Ejemplo:
payment_triggers
string[] | null

Los eventos de pago a los que se suscribe el webhook.

Ejemplo:
report_triggers
string[] | null

Los eventos de reportes a los que se suscribe el webhook.

Ejemplo:
subscription_triggers
string[] | null

Los eventos de suscripción a los que se suscribe el webhook.

Ejemplo:
onboarding_triggers
string[] | null

Los eventos de onboarding a los que se suscribe el webhook.

Ejemplo:
renewal_days
integer | null

Cuántos días antes de una renovación Yuno envía la notificación CLOSE_TO_RENEWAL.

Ejemplo:

5

created_at
string<date-time>

La fecha y hora en que se creó el webhook, en ISO 8601.

Ejemplo:

"2026-07-09T13:05:36.482913Z"

updated_at
string<date-time>

La fecha y hora de la última actualización del webhook, en ISO 8601. Coincide con created_at hasta que actualizas el webhook por primera vez.

Ejemplo:

"2026-07-11T16:20:44.918330Z"