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

# Rotate webhook signing secret

> Required scope: `partner.webhooks.manage`.



## OpenAPI

````yaml /api-reference/openapi.json post /webhooks/subscriptions/{subscription}/rotate-secret
openapi: 3.1.0
info:
  title: Digital Florists Partner API
  version: v1
  description: >-
    Orders, customers and products (reads plus customer creation) and outbound
    webhooks. Bearer authentication; per-shop base URL.
servers:
  - url: https://{shop_domain}/api/partner/v1
    description: Shop
    variables:
      shop_domain:
        default: your-shop.example
security:
  - bearerAuth: []
paths:
  /webhooks/subscriptions/{subscription}/rotate-secret:
    post:
      tags:
        - Webhook subscriptions
      summary: Rotate webhook signing secret
      description: 'Required scope: `partner.webhooks.manage`.'
      operationId: partner.v1.webhooks.subscriptions.rotate_secret
      parameters:
        - name: subscription
          in: path
          required: true
          schema:
            type: integer
            format: int64
            minimum: 1
          example: 42
      responses:
        '200':
          description: The webhook subscription with a freshly rotated signing secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionWithSecret'
              examples:
                success:
                  summary: Example response
                  value:
                    id: 42
                    url: https://partner.example.com/webhooks/digital-florists
                    events:
                      - order.created
                      - order.payment_status_changed
                    active: true
                    disabled_reason: null
                    secret_last_four: a1b2
                    last_delivered_at: null
                    created_at: '2026-06-27T10:15:00+01:00'
                    updated_at: '2026-06-27T10:15:00+01:00'
                    signing_secret: >-
                      f8c7e6d5c4b3a2918070605040302010f8c7e6d5c4b3a2918070605040302010
        '401':
          $ref: '#/components/responses/AuthenticationException'
          description: >-
            Authentication failed, or the token is missing, invalid, expired, or
            revoked.
        '403':
          $ref: '#/components/responses/ForbiddenError'
          description: >-
            The token lacks the required scope, or API access is not enabled for
            this shop.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: No matching resource for this shop.
        '429':
          $ref: '#/components/responses/RateLimitError'
          description: >-
            Rate limit exceeded. Retry after the period given in the Retry-After
            header.
        '500':
          $ref: '#/components/responses/ServerError'
          description: An unexpected server error occurred.
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
          description: The partner API is temporarily disabled. Retry later.
      security:
        - bearerAuth: []
components:
  schemas:
    WebhookSubscriptionWithSecret:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
          format: uri
          example: https://partner.example.com/webhooks/digital-florists
        events:
          type: array
          items:
            type: string
            enum:
              - order.created
              - order.updated
              - order.assigned
              - order.status_changed
              - order.payment_status_changed
        active:
          type: boolean
        disabled_reason:
          type:
            - string
            - 'null'
          enum:
            - endpoint_4xx
            - endpoint_unsafe
            - entitlement_lost
            - manual
            - delivery_failures_exhausted
            - null
          example: null
        secret_last_four:
          type:
            - string
            - 'null'
          example: a1b2
        last_delivered_at:
          type:
            - string
            - 'null'
          format: date-time
          example: null
        created_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-06-27T10:15:00+01:00'
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-06-27T10:15:00+01:00'
        signing_secret:
          type: string
          description: Plaintext signing secret. Shown once on creation or rotation.
          example: f8c7e6d5c4b3a2918070605040302010f8c7e6d5c4b3a2918070605040302010
      required:
        - id
        - url
        - events
        - active
        - disabled_reason
        - secret_last_four
        - last_delivered_at
        - created_at
        - updated_at
        - signing_secret
      title: WebhookSubscriptionWithSecret
      example:
        id: 42
        url: https://partner.example.com/webhooks/digital-florists
        events:
          - order.created
          - order.payment_status_changed
        active: true
        disabled_reason: null
        secret_last_four: a1b2
        last_delivered_at: null
        created_at: '2026-06-27T10:15:00+01:00'
        updated_at: '2026-06-27T10:15:00+01:00'
        signing_secret: f8c7e6d5c4b3a2918070605040302010f8c7e6d5c4b3a2918070605040302010
  responses:
    AuthenticationException:
      description: Unauthenticated
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
    ForbiddenError:
      description: >-
        The token lacks the required scope, or API access is not enabled for
        this shop.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
    NotFoundError:
      description: No matching resource for this shop.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
    RateLimitError:
      description: >-
        Rate limit exceeded. Retry after the period given in the Retry-After
        header.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
              retry_after:
                type:
                  - integer
                  - 'null'
                description: Seconds to wait before retrying.
            required:
              - error
              - message
              - retry_after
    ServerError:
      description: An unexpected server error occurred.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
    ServiceUnavailableError:
      description: The partner API is temporarily disabled. Retry later.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````