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

# Delete a Webhook

> Deletes a webhook and stops the notifications Yuno sends to its URL

Deletes a webhook. Yuno stops sending notifications to its `url`, and returns the webhook it deleted so you keep a record of the events it was subscribed to.

To stop the notifications and keep the configuration, set `state` to `INACTIVE` with [Update a Webhook](/reference/webhooks/update-webhook) instead.


## OpenAPI

````yaml openapi/webhooks/manage-webhooks.json DELETE /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}:
    delete:
      summary: Delete a Webhook
      description: >-
        Deletes a webhook. Yuno stops sending notifications to its URL, and
        returns the webhook it deleted.
      operationId: delete-webhook
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: >-
            The unique identifier of the webhook, as returned by [List
            Webhooks](/reference/webhooks/list-webhooks).
          schema:
            type: string
            example: '12345'
        - name: account_id
          in: query
          required: true
          description: The unique identifier of the account the webhook belongs to.
          schema:
            type: string
            format: uuid
            example: 493e9374-510a-4201-9e09-de669d75f256
            x-default: 493e9374-510a-4201-9e09-de669d75f256
      responses:
        '200':
          description: The webhook you deleted.
          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: null
                renewal_days: 5
                created_at: '2026-07-09T13:05:36.482913Z'
                updated_at: '2026-07-09T13:05:36.482913Z'
        '400':
          $ref: '#/components/responses/InvalidAccountRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
        '502':
          $ref: '#/components/responses/UpstreamError'
components:
  schemas:
    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
    WebhookRequestError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - WEBHOOK_INVALID_REQUEST
            - INVALID_ACCOUNT_ID
        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
    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:
    InvalidAccountRequest:
      description: The `account_id` is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookRequestError'
          examples:
            Missing account_id:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - account_id is required.
            Invalid account_id:
              value:
                code: INVALID_ACCOUNT_ID
                messages:
                  - Account id is invalid
    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.
    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>

````