> ## 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.

# Update a Webhook

> Updates a webhook, including its state and the credentials Yuno delivers with

Updates a webhook. Send `account_id` and the fields you want to change. Use it to point a webhook at a new `url`, change the events it receives, rotate the credentials Yuno delivers with, or deactivate it.

`state` turns deliveries on and off: `INACTIVE` stops them and keeps the configuration, and `ACTIVE` resumes them. A rotated `api_key`, `secret` or `hmac_client_secret` applies to the next delivery. To remove `renewal_days`, send `clear_renewal_days` as `true` on its own.

<Note>
  Trigger fields are replaced, not merged. Send the full list of events you want the webhook subscribed to, and omit the field to leave it as it is.
</Note>

The [OAuth2](/reference/webhooks#oauth2) fields are configured as a set: when you change any of `oauth2_authentication_url`, `oauth2_client_id`, `oauth2_client_secret` or `oauth2_grant_type`, send the four of them.

Renaming a webhook to a `name` the account already uses, or moving it onto a `url` where another webhook listens to one of the same events, returns `409 WEBHOOK_ALREADY_EXISTS`.


## OpenAPI

````yaml openapi/webhooks/manage-webhooks.json PATCH /webhooks/{webhook_id}
openapi: 3.1.0
info:
  title: webhooks-manage-webhooks
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /webhooks/{webhook_id}:
    patch:
      summary: Update a Webhook
      description: >-
        Updates a webhook. Send only the fields you want to change, including
        the state and any rotated secret.
      operationId: update-webhook
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: >-
            The unique identifier of the webhook, as returned by [Create a
            Webhook](/reference/webhooks/create-webhook).
          schema:
            type: string
            example: '12345'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdateInput'
            example:
              account_id: 493e9374-510a-4201-9e09-de669d75f256
              state: INACTIVE
              secret: my-rotated-secret
      responses:
        '200':
          description: The updated webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: '12345'
                account_id: 493e9374-510a-4201-9e09-de669d75f256
                name: Production payments listener
                state: INACTIVE
                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: null
                renewal_days: 5
                created_at: '2026-07-09T13:05:36.482913Z'
                updated_at: '2026-07-11T16:20:44.918330Z'
        '400':
          $ref: '#/components/responses/InvalidUpdateRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
        '409':
          $ref: '#/components/responses/WebhookConflict'
        '502':
          $ref: '#/components/responses/UpstreamError'
components:
  schemas:
    WebhookUpdateInput:
      type: object
      required:
        - account_id
      properties:
        account_id:
          type: string
          format: uuid
          description: The unique identifier of the account the webhook belongs to.
          example: 493e9374-510a-4201-9e09-de669d75f256
        name:
          type: string
          description: Your name for the webhook. It must be unique within the account.
          example: Production payments listener
        state:
          type: string
          description: >-
            Set it to `INACTIVE` to stop the deliveries while keeping the
            configuration, and back to `ACTIVE` to resume them.
          enum:
            - ACTIVE
            - INACTIVE
          example: INACTIVE
        url:
          type: string
          description: >-
            The endpoint Yuno sends the notifications to. It must be an `http`
            or `https` URL that resolves to a public, routable address.
          example: https://api.acme.com/yuno/webhooks
        api_key:
          type: string
          description: Replaces the `x-api-key` Yuno sends on every delivery.
          example: my-webhook-key-v2
        secret:
          type: string
          description: Replaces the `x-secret` Yuno sends on every delivery.
          example: my-rotated-secret
        hmac_client_secret:
          type: string
          description: Replaces the key Yuno signs the payload with.
          example: my-rotated-hmac-secret
        oauth2_authentication_url:
          type: string
          description: >-
            Your token endpoint. It must use HTTPS. Send
            `oauth2_authentication_url`, `oauth2_client_id`,
            `oauth2_client_secret` and `oauth2_grant_type` together.
          example: https://api.acme.com/oauth/token
        oauth2_client_id:
          type: string
          description: >-
            The client identifier Yuno authenticates with. Send
            `oauth2_authentication_url`, `oauth2_client_id`,
            `oauth2_client_secret` and `oauth2_grant_type` together.
          example: acme_client_id
        oauth2_client_secret:
          type: string
          description: >-
            The client secret Yuno authenticates with. Send
            `oauth2_authentication_url`, `oauth2_client_id`,
            `oauth2_client_secret` and `oauth2_grant_type` together.
          example: acme_client_secret
        oauth2_grant_type:
          type: string
          description: >-
            The grant type Yuno requests the token with. Send
            `oauth2_authentication_url`, `oauth2_client_id`,
            `oauth2_client_secret` and `oauth2_grant_type` together.
          example: client_credentials
        oauth2_scope:
          type: string
          description: The scope Yuno requests the token with.
          example: webhooks:write
        oauth2_authorization_name:
          type: string
          description: The header Yuno sends the token in. Defaults to `Authorization`.
          example: Authorization
        oauth2_include_client_id:
          type: boolean
          description: Send the client identifier as a header on the token request as well.
          example: true
        enrollment_triggers:
          type: array
          description: Replaces the enrollment events the webhook subscribes to.
          items:
            type: string
            enum:
              - ENROLL
              - UNENROLL
          example:
            - ENROLL
        payment_triggers:
          type: array
          description: Replaces the payment events the webhook subscribes to.
          items:
            type: string
            enum:
              - AUTHORIZE
              - CANCEL
              - CAPTURE
              - CHARGEBACK
              - PRECHARGEBACK
              - PURCHASE
              - REFUND
              - VERIFY
          example:
            - AUTHORIZE
            - CAPTURE
            - REFUND
        report_triggers:
          type: array
          description: Replaces the report events the webhook subscribes to.
          items:
            type: string
            enum:
              - CREATE
              - UPDATE
          example:
            - UPDATE
        subscription_triggers:
          type: array
          description: Replaces the subscription events the webhook subscribes to.
          items:
            type: string
            enum:
              - ACTIVE
              - CANCEL
              - CLOSE_TO_RENEWAL
              - COMPLETE
              - CREATE
              - PAUSE
              - RESUME
          example:
            - CREATE
            - CANCEL
        onboarding_triggers:
          type: array
          description: Replaces the onboarding events the webhook subscribes to.
          items:
            type: string
            enum:
              - BLOCKED
              - CANCELLED
              - CREATED
              - DECLINED
              - ERROR
              - EXPIRED
              - INACTIVE
              - PENDING
              - SUCCEEDED
              - TRANSFERRED
              - UNBLOCKED
          example:
            - CREATED
            - SUCCEEDED
        renewal_days:
          type: integer
          description: >-
            How many days before a renewal Yuno sends the `CLOSE_TO_RENEWAL`
            notification. It must be 1 or more. Send it on its own, not together
            with `clear_renewal_days`.
          example: 5
        clear_renewal_days:
          type: boolean
          description: >-
            Set it to `true` to remove `renewal_days`. Send it on its own, not
            together with `renewal_days`.
          example: true
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the webhook.
          example: '12345'
        account_id:
          type: string
          format: uuid
          description: The unique identifier of the account the webhook belongs to.
          example: 493e9374-510a-4201-9e09-de669d75f256
        name:
          type: string
          description: Your name for the webhook.
          example: Production payments listener
        state:
          type: string
          description: >-
            `ACTIVE` webhooks receive notifications, `INACTIVE` ones do not. A
            webhook starts out `ACTIVE`.
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        url:
          type: string
          description: The endpoint Yuno sends the notifications to.
          example: https://api.acme.com/yuno/webhooks
        api_key:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        secret:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        hmac_client_secret:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        oauth2_authentication_url:
          type:
            - string
            - 'null'
          description: Your token endpoint.
          example: https://api.acme.com/oauth/token
        oauth2_client_secret:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        oauth2_client_id:
          type:
            - string
            - 'null'
          description: The client identifier Yuno authenticates with.
          example: acme_client_id
        oauth2_grant_type:
          type:
            - string
            - 'null'
          description: The grant type Yuno requests the token with.
          example: client_credentials
        oauth2_scope:
          type:
            - string
            - 'null'
          description: The scope Yuno requests the token with.
          example: webhooks:write
        oauth2_authorization_name:
          type:
            - string
            - 'null'
          description: The header Yuno sends the token in.
          example: Authorization
        oauth2_include_client_id:
          type: boolean
          description: >-
            Whether Yuno also sends the client identifier as a header on the
            token request.
          example: true
        enrollment_triggers:
          type:
            - array
            - 'null'
          description: The enrollment events the webhook subscribes to.
          items:
            type: string
          example:
            - ENROLL
            - UNENROLL
        payment_triggers:
          type:
            - array
            - 'null'
          description: The payment events the webhook subscribes to.
          items:
            type: string
          example:
            - AUTHORIZE
            - CAPTURE
            - REFUND
        report_triggers:
          type:
            - array
            - 'null'
          description: The report events the webhook subscribes to.
          items:
            type: string
          example:
            - UPDATE
        subscription_triggers:
          type:
            - array
            - 'null'
          description: The subscription events the webhook subscribes to.
          items:
            type: string
          example:
            - CREATE
            - CLOSE_TO_RENEWAL
        onboarding_triggers:
          type:
            - array
            - 'null'
          description: The onboarding events the webhook subscribes to.
          items:
            type: string
          example:
            - CREATED
            - SUCCEEDED
        renewal_days:
          type:
            - integer
            - 'null'
          description: >-
            How many days before a renewal Yuno sends the `CLOSE_TO_RENEWAL`
            notification.
          example: 5
        created_at:
          type: string
          description: The date and time the webhook was created, in ISO 8601.
          example: '2026-07-09T13:05:36.482913Z'
          format: date-time
        updated_at:
          type: string
          description: >-
            The date and time the webhook was last updated, in ISO 8601. It
            matches `created_at` until you update the webhook for the first
            time.
          example: '2026-07-11T16:20:44.918330Z'
          format: date-time
    WebhookWriteRequestError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - WEBHOOK_INVALID_REQUEST
            - INVALID_ACCOUNT_ID
            - WEBHOOK_INVALID_TRIGGER
            - WEBHOOK_INVALID_OAUTH2
            - WEBHOOK_INVALID_RENEWAL_DAYS
            - WEBHOOK_URL_UNSAFE
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
    WebhookAuthError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - NOT_AUTHENTICATED
            - INVALID_CREDENTIALS
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
    WebhookNotFoundError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - WEBHOOK_NOT_FOUND
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
    WebhookConflictError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - WEBHOOK_ALREADY_EXISTS
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
    WebhookUpstreamError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - WEBHOOK_UPSTREAM_ERROR
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
  responses:
    InvalidUpdateRequest:
      description: The request is invalid. The `code` tells you which rule it broke.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookWriteRequestError'
          examples:
            Missing account_id:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - account_id is required.
            Invalid state:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - state must be ACTIVE or INACTIVE.
            Conflicting renewal fields:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - renewal_days and clear_renewal_days cannot be set together.
            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: Your API credentials are missing or invalid.
      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
    WebhookNotFound:
      description: There is no webhook with that identifier on the account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookNotFoundError'
          examples:
            Not found:
              value:
                code: WEBHOOK_NOT_FOUND
                messages:
                  - The webhook does not exist for this account.
    WebhookConflict:
      description: >-
        The account already has a webhook with that name, or one with the same
        URL that listens to one of the same events.
      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: The webhook service is temporarily unavailable.
      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>

````