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

# Replace a subscription

> Fully replace an existing webhook subscription using PUT semantics. Provide all fields – use this to update a subscription's target endpoint URL.

Use this endpoint to point an existing subscription at a different `destination_url` – for example, when you migrate to a new server or change your webhook handler path. The event type itself is identified by the path and cannot be changed; unsubscribe and create a new subscription if you need a different event type.

<Note>
  Replacing a subscription does **not** rotate the `signature_key`. Your existing key remains valid and continues to sign every
  delivery for this event type. To issue a new signing key, use [Rotate Signature
  Key](/api-reference/webhooks/rotate-signature-key).
</Note>


## OpenAPI

````yaml PUT /v1/webhooks/{type}
openapi: 3.0.0
info:
  version: 0.0.1
  title: Tilta API
  description: Tilta API documentation
servers:
  - url: https://api.tilta.io
    description: Tilta Production API
  - url: https://api.tilta-sandbox.io
    description: Tilta Sandbox API
security: []
paths:
  /v1/webhooks/{type}:
    put:
      tags:
        - Webhooks
      summary: Replace webhook subscription
      description: >-
        Replaces the specified Webhook subscription. This is a full-replacement
        update: every field in the request body must be provided.
      parameters:
        - schema:
            type: string
            enum:
              - BUYER
              - BUYER.CREATED
              - BUYER.UPDATED
              - FACILITY
              - FACILITY.CREATION
              - FACILITY.CREATION.ACCEPTED
              - FACILITY.CREATION.IN_REVIEW
              - FACILITY.CREATION.REJECTED
              - FACILITY.EXPIRED
              - FACILITY.FROZEN
              - FACILITY.INCREASE
              - FACILITY.INCREASE.ACCEPTED
              - FACILITY.INCREASE.IN_REVIEW
              - FACILITY.INCREASE.REJECTED
              - FACILITY.RENEWAL
              - FACILITY.RENEWAL.ACCEPTED
              - FACILITY.RENEWAL.IN_REVIEW
              - FACILITY.RENEWAL.REJECTED
              - FACILITY.UNFROZEN
              - INVOICE
              - INVOICE.CLOSED
              - INVOICE.CREATED
              - INVOICE.DUE
              - INVOICE.FILE
              - INVOICE.FILE.CREATED
              - INVOICE.FILE.DELETED
              - INVOICE.FILE.REPLACED
              - INVOICE.FINANCING
              - INVOICE.FINANCING.PAID_OUT
              - ORDER
              - ORDER.CANCELLED
              - ORDER.CLOSED
              - ORDER.CONFIRMED
              - ORDER.DISBURSED
              - ORDER.EXPIRED
            description: >-
              The webhook's type. Supports the hierarchical dot-notation
              taxonomy; subscribing to a parent (e.g. `FACILITY`) implicitly
              subscribes to every descendant event (e.g.
              `FACILITY.CREATION.ACCEPTED`). Other valid values include
              `ORDER.CONFIRMED` and `INVOICE.DUE`.
            example: FACILITY.CREATION.ACCEPTED
          required: true
          name: type
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                destination_url:
                  type: string
                  format: uri
                  description: >-
                    Where the webhook should be sent to. This must be an
                    endpoint that handles POST requests.
              required:
                - destination_url
              additionalProperties: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  destination_url:
                    type: string
                    format: uri
                    description: >-
                      Where the webhook should be sent to. This must be an
                      endpoint that handles POST requests.
                  type:
                    type: string
                    enum:
                      - BUYER
                      - BUYER.CREATED
                      - BUYER.UPDATED
                      - FACILITY
                      - FACILITY.CREATION
                      - FACILITY.CREATION.ACCEPTED
                      - FACILITY.CREATION.IN_REVIEW
                      - FACILITY.CREATION.REJECTED
                      - FACILITY.EXPIRED
                      - FACILITY.FROZEN
                      - FACILITY.INCREASE
                      - FACILITY.INCREASE.ACCEPTED
                      - FACILITY.INCREASE.IN_REVIEW
                      - FACILITY.INCREASE.REJECTED
                      - FACILITY.RENEWAL
                      - FACILITY.RENEWAL.ACCEPTED
                      - FACILITY.RENEWAL.IN_REVIEW
                      - FACILITY.RENEWAL.REJECTED
                      - FACILITY.UNFROZEN
                      - INVOICE
                      - INVOICE.CLOSED
                      - INVOICE.CREATED
                      - INVOICE.DUE
                      - INVOICE.FILE
                      - INVOICE.FILE.CREATED
                      - INVOICE.FILE.DELETED
                      - INVOICE.FILE.REPLACED
                      - INVOICE.FINANCING
                      - INVOICE.FINANCING.PAID_OUT
                      - ORDER
                      - ORDER.CANCELLED
                      - ORDER.CLOSED
                      - ORDER.CONFIRMED
                      - ORDER.DISBURSED
                      - ORDER.EXPIRED
                    description: >-
                      The webhook's type. Supports the hierarchical dot-notation
                      taxonomy; subscribing to a parent (e.g. `FACILITY`)
                      implicitly subscribes to every descendant event (e.g.
                      `FACILITY.CREATION.ACCEPTED`). Other valid values include
                      `ORDER.CONFIRMED` and `INVOICE.DUE`.
                    example: FACILITY.CREATION.ACCEPTED
                required:
                  - destination_url
                  - type
                additionalProperties: false
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestSchema'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorizedRequestSchema'
      security:
        - bearerAuth: []
components:
  schemas:
    badRequestSchema:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: BAD_REQUEST
        error:
          type: string
          description: Error message for debugging purposes
          example: Request validation failed. 1 issue found.
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Issue code
                example: INVALID_TYPE
              path:
                type: string
                description: Issue path starting with body, params, querystring, or headers
                example: body.registered_at
              message:
                type: string
                description: Issue message for debugging purposes
                example: Invalid type
            required:
              - code
              - path
              - message
          description: List of issues
          example:
            - code: INVALID_TYPE
              path: body.registered_at
              message: Invalid type
      required:
        - code
        - error
        - issues
      description: Bad Request, see error message for details.
      example:
        code: BAD_REQUEST
        error: Request validation failed. 1 issue found.
        issues:
          - code: INVALID_TYPE
            path: body.registered_at
            message: Invalid type
    unauthorizedRequestSchema:
      type: object
      properties:
        error:
          type: string
          description: Error details.
          example: Unauthorized
        code:
          type: string
          description: Error code.
          example: UNAUTHORIZED
      required:
        - error
        - code
      description: Unauthorized Request.
      example:
        error: Unauthorized
        code: UNAUTHORIZED
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Tilta API key, sent as `Bearer <key>`.

````