> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Crear un webhook

> Crea un webhook en estado activo, suscrito a los eventos que selecciones

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](https://docs.y.uno/es/reference/webhooks.md#triggers). La respuesta incluye el `id` que usas para [consultarlo](https://docs.y.uno/es/reference/webhooks/retrieve-webhook.md), [actualizarlo](https://docs.y.uno/es/reference/webhooks/update-webhook.md) y [eliminarlo](https://docs.y.uno/es/reference/webhooks/delete-webhook.md).

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](https://docs.y.uno/es/reference/webhooks.md#delivery-authentication). Son opcionales y puedes combinarlos. Los secretos que configures se devuelven enmascarados, y el resto se devuelve como `null`.

> [!NOTE]
>
> Para definir `oauth2_scope`, usa [Actualizar un webhook](https://docs.y.uno/es/reference/webhooks/update-webhook.md).

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.


## OpenAPI

````yaml openapi/es/webhooks/manage-webhooks.json POST /webhooks
openapi: 3.1.0
info:
  title: webhooks-manage-webhooks
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /webhooks:
    post:
      summary: Crear un webhook
      description: >-
        Crea un webhook en estado activo, suscrito a los eventos que
        selecciones. Requiere al menos un trigger y empieza a recibir
        notificaciones de inmediato.
      operationId: create-webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateInput'
            example:
              account_id: 493e9374-510a-4201-9e09-de669d75f256
              name: Production payments listener
              url: https://api.acme.com/yuno/webhooks
              api_key: my-webhook-key
              secret: my-webhook-secret
              hmac_client_secret: my-hmac-secret
              enrollment_triggers:
                - ENROLL
                - UNENROLL
              payment_triggers:
                - AUTHORIZE
                - CAPTURE
                - REFUND
              subscription_triggers:
                - CREATE
                - CLOSE_TO_RENEWAL
              renewal_days: 5
      responses:
        '201':
          description: >-
            El webhook que creaste. Los secretos que configuraste se devuelven
            enmascarados, y los que omitiste se devuelven como null.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: '12345'
                account_id: 493e9374-510a-4201-9e09-de669d75f256
                name: Production payments listener
                state: ACTIVE
                url: https://api.acme.com/yuno/webhooks
                api_key: '***'
                secret: '***'
                hmac_client_secret: '***'
                oauth2_authentication_url: null
                oauth2_client_secret: null
                oauth2_client_id: null
                oauth2_grant_type: null
                oauth2_scope: null
                oauth2_authorization_name: null
                oauth2_include_client_id: false
                enrollment_triggers:
                  - ENROLL
                  - UNENROLL
                payment_triggers:
                  - AUTHORIZE
                  - CAPTURE
                  - REFUND
                report_triggers: []
                subscription_triggers:
                  - CREATE
                  - CLOSE_TO_RENEWAL
                onboarding_triggers: []
                renewal_days: 5
                created_at: '2026-07-09T13:05:36.482913Z'
                updated_at: '2026-07-09T13:05:36.482913Z'
        '400':
          $ref: '#/components/responses/InvalidCreateRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/WebhookConflict'
        '502':
          $ref: '#/components/responses/UpstreamError'
components:
  schemas:
    WebhookCreateInput:
      type: object
      required:
        - account_id
        - name
        - url
      properties:
        account_id:
          type: string
          format: uuid
          description: El identificador único de la cuenta a la que pertenece el webhook.
          example: 493e9374-510a-4201-9e09-de669d75f256
        name:
          type: string
          description: Tu nombre para el webhook. Debe ser único dentro de la cuenta.
          example: Production payments listener
        url:
          type: string
          description: >-
            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.
          example: https://api.acme.com/yuno/webhooks
        api_key:
          type: string
          description: >-
            Se envía a tu endpoint como el encabezado `x-api-key` en cada
            entrega.
          example: my-webhook-key
        secret:
          type: string
          description: >-
            Se envía a tu endpoint como el encabezado `x-secret` en cada
            entrega.
          example: my-webhook-secret
        hmac_client_secret:
          type: string
          description: >-
            La clave con la que Yuno firma el payload. La firma viaja en el
            encabezado `x-hmac-signature`.
          example: my-hmac-secret
        oauth2_authentication_url:
          type: string
          description: >-
            Tu endpoint de token. Debe usar HTTPS. Envía
            `oauth2_authentication_url`, `oauth2_client_id`,
            `oauth2_client_secret` y `oauth2_grant_type` juntos.
          example: https://api.acme.com/oauth/token
        oauth2_client_id:
          type: string
          description: >-
            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.
          example: acme_client_id
        oauth2_client_secret:
          type: string
          description: >-
            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.
          example: acme_client_secret
        oauth2_grant_type:
          type: string
          description: >-
            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.
          example: client_credentials
        oauth2_authorization_name:
          type: string
          description: >-
            El encabezado en el que Yuno envía el token. Por defecto es
            `Authorization`.
          example: Authorization
        oauth2_include_client_id:
          type: boolean
          description: >-
            Envía también el identificador de cliente como encabezado en la
            solicitud del token.
          example: false
        enrollment_triggers:
          type: array
          description: Los eventos de inscripción a los que se suscribe el webhook.
          items:
            type: string
            enum:
              - ENROLL
              - UNENROLL
          example:
            - ENROLL
            - UNENROLL
        payment_triggers:
          type: array
          description: Los eventos de pago a los que se suscribe el webhook.
          items:
            type: string
            enum:
              - AUTHORIZE
              - CANCEL
              - CAPTURE
              - CHARGEBACK
              - PRECHARGEBACK
              - PURCHASE
              - REFUND
              - SPLIT_UPDATE
              - VERIFY
          example:
            - AUTHORIZE
            - CAPTURE
            - REFUND
        report_triggers:
          type: array
          description: Los eventos de reportes a los que se suscribe el webhook.
          items:
            type: string
            enum:
              - CREATE
              - UPDATE
          example:
            - UPDATE
        subscription_triggers:
          type: array
          description: Los eventos de suscripción a los que se suscribe el webhook.
          items:
            type: string
            enum:
              - ACTIVE
              - CANCEL
              - CLOSE_TO_RENEWAL
              - COMPLETE
              - CREATE
              - CREATION_FAILED
              - PAUSE
              - PLAN_CHANGE_CANCELED
              - PLAN_CHANGE_SCHEDULED
              - PLAN_CHANGED
              - PROMOTION_APPLIED
              - RESUME
          example:
            - CREATE
            - CLOSE_TO_RENEWAL
        onboarding_triggers:
          type: array
          description: Los eventos de onboarding a los que se suscribe el webhook.
          items:
            type: string
            enum:
              - BLOCKED
              - CANCELLED
              - CREATED
              - DECLINED
              - ERROR
              - EXPIRED
              - INACTIVE
              - PENDING
              - SUCCEEDED
              - TRANSFERRED
              - UNBLOCKED
          example:
            - CREATED
            - SUCCEEDED
        renewal_days:
          type: integer
          description: >-
            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`.
          example: 5
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: El identificador único del webhook.
          example: '12345'
        account_id:
          type: string
          format: uuid
          description: El identificador único de la cuenta a la que pertenece el webhook.
          example: 493e9374-510a-4201-9e09-de669d75f256
        name:
          type: string
          description: Tu nombre para el webhook.
          example: Production payments listener
        state:
          type: string
          description: >-
            Los webhooks `ACTIVE` reciben notificaciones, los `INACTIVE` no. Un
            webhook empieza como `ACTIVE`.
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        url:
          type: string
          description: El endpoint al que Yuno envía las notificaciones.
          example: https://api.acme.com/yuno/webhooks
        api_key:
          type:
            - string
            - 'null'
          description: Enmascarado como `***`, o `null` cuando no lo has configurado.
          example: '***'
        secret:
          type:
            - string
            - 'null'
          description: Enmascarado como `***`, o `null` cuando no lo has configurado.
          example: '***'
        hmac_client_secret:
          type:
            - string
            - 'null'
          description: Enmascarado como `***`, o `null` cuando no lo has configurado.
          example: '***'
        oauth2_authentication_url:
          type:
            - string
            - 'null'
          description: Tu endpoint de token.
          example: https://api.acme.com/oauth/token
        oauth2_client_secret:
          type:
            - string
            - 'null'
          description: Enmascarado como `***`, o `null` cuando no lo has configurado.
          example: '***'
        oauth2_client_id:
          type:
            - string
            - 'null'
          description: El identificador de cliente con el que Yuno se autentica.
          example: acme_client_id
        oauth2_grant_type:
          type:
            - string
            - 'null'
          description: El tipo de concesión con el que Yuno solicita el token.
          example: client_credentials
        oauth2_scope:
          type:
            - string
            - 'null'
          description: El alcance con el que Yuno solicita el token.
          example: webhooks:write
        oauth2_authorization_name:
          type:
            - string
            - 'null'
          description: El encabezado en el que Yuno envía el token.
          example: Authorization
        oauth2_include_client_id:
          type: boolean
          description: >-
            Indica si Yuno también envía el identificador de cliente como
            encabezado en la solicitud del token.
          example: true
        enrollment_triggers:
          type:
            - array
            - 'null'
          description: Los eventos de inscripción a los que se suscribe el webhook.
          items:
            type: string
          example:
            - ENROLL
            - UNENROLL
        payment_triggers:
          type:
            - array
            - 'null'
          description: Los eventos de pago a los que se suscribe el webhook.
          items:
            type: string
          example:
            - AUTHORIZE
            - CAPTURE
            - REFUND
        report_triggers:
          type:
            - array
            - 'null'
          description: Los eventos de reportes a los que se suscribe el webhook.
          items:
            type: string
          example:
            - UPDATE
        subscription_triggers:
          type:
            - array
            - 'null'
          description: Los eventos de suscripción a los que se suscribe el webhook.
          items:
            type: string
          example:
            - CREATE
            - CLOSE_TO_RENEWAL
        onboarding_triggers:
          type:
            - array
            - 'null'
          description: Los eventos de onboarding a los que se suscribe el webhook.
          items:
            type: string
          example:
            - CREATED
            - SUCCEEDED
        renewal_days:
          type:
            - integer
            - 'null'
          description: >-
            Cuántos días antes de una renovación Yuno envía la notificación
            `CLOSE_TO_RENEWAL`.
          example: 5
        created_at:
          type: string
          description: La fecha y hora en que se creó el webhook, en ISO 8601.
          example: '2026-07-09T13:05:36.482913Z'
          format: date-time
        updated_at:
          type: string
          description: >-
            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.
          example: '2026-07-11T16:20:44.918330Z'
          format: date-time
    WebhookWriteRequestError:
      type: object
      properties:
        code:
          type: string
          description: Código de error legible por máquina.
          enum:
            - WEBHOOK_INVALID_REQUEST
            - INVALID_ACCOUNT_ID
            - WEBHOOK_INVALID_TRIGGER
            - WEBHOOK_INVALID_OAUTH2
            - WEBHOOK_INVALID_RENEWAL_DAYS
            - WEBHOOK_URL_UNSAFE
        messages:
          type: array
          description: Descripción legible del error.
          items:
            type: string
    WebhookAuthError:
      type: object
      properties:
        code:
          type: string
          description: Código de error legible por máquina.
          enum:
            - NOT_AUTHENTICATED
            - INVALID_CREDENTIALS
        messages:
          type: array
          description: Descripción legible del error.
          items:
            type: string
    WebhookConflictError:
      type: object
      properties:
        code:
          type: string
          description: Código de error legible por máquina.
          enum:
            - WEBHOOK_ALREADY_EXISTS
        messages:
          type: array
          description: Descripción legible del error.
          items:
            type: string
    WebhookUpstreamError:
      type: object
      properties:
        code:
          type: string
          description: Código de error legible por máquina.
          enum:
            - WEBHOOK_UPSTREAM_ERROR
        messages:
          type: array
          description: Descripción legible del error.
          items:
            type: string
  responses:
    InvalidCreateRequest:
      description: La solicitud no es válida. El `code` te indica qué regla incumplió.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookWriteRequestError'
          examples:
            Missing required field:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - account_id, name and url are required.
            No triggers:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - at least one trigger is required.
            Invalid trigger:
              value:
                code: WEBHOOK_INVALID_TRIGGER
                messages:
                  - One or more webhook triggers are invalid.
            Incomplete OAuth2:
              value:
                code: WEBHOOK_INVALID_OAUTH2
                messages:
                  - OAuth2 configuration is incomplete or inconsistent.
            Invalid renewal_days:
              value:
                code: WEBHOOK_INVALID_RENEWAL_DAYS
                messages:
                  - >-
                    renewal_days is only valid when subscription_triggers
                    contains CLOSE_TO_RENEWAL
            Invalid account_id:
              value:
                code: INVALID_ACCOUNT_ID
                messages:
                  - Account id is invalid
            Unsafe url:
              value:
                code: WEBHOOK_URL_UNSAFE
                messages:
                  - >-
                    The webhook url is not allowed; it must resolve to a public,
                    routable address.
    Unauthorized:
      description: Tus credenciales de API faltan o no son válidas.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookAuthError'
          examples:
            Not authenticated:
              value:
                code: NOT_AUTHENTICATED
                messages:
                  - Not authenticated
            Invalid credentials:
              value:
                code: INVALID_CREDENTIALS
                messages:
                  - Invalid Credentials
    WebhookConflict:
      description: >-
        La cuenta ya tiene un webhook con ese nombre, o uno con la misma URL que
        escucha alguno de los mismos eventos.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookConflictError'
          examples:
            Already exists:
              value:
                code: WEBHOOK_ALREADY_EXISTS
                messages:
                  - >-
                    A webhook with the same name, or url and trigger(s), already
                    exists for this account.
    UpstreamError:
      description: El servicio de webhooks no está disponible temporalmente.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookUpstreamError'
          examples:
            Service unavailable:
              value:
                code: WEBHOOK_UPSTREAM_ERROR
                messages:
                  - The webhook service is temporarily unavailable.
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.