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

# Create webhook subscription

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



## OpenAPI

````yaml /api-reference/openapi.json post /webhooks/subscriptions
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:
    post:
      tags:
        - Webhook subscriptions
      summary: Create webhook subscription
      description: 'Required scope: `partner.webhooks.manage`.'
      operationId: partner.v1.webhooks.subscriptions.store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  maxLength: 2048
                active:
                  type: boolean
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - order.created
                      - order.updated
                      - order.assigned
                      - order.status_changed
                      - order.payment_status_changed
                  minItems: 1
              required:
                - url
                - events
      responses:
        '201':
          description: >-
            The created webhook subscription. The signing secret is shown once,
            here, on creation.
          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.
        '409':
          description: A webhook subscription already exists for this URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: duplicate_subscription
                  message:
                    type: string
                    example: A webhook subscription already exists for this URL.
                  existing_subscription_id:
                    type: integer
                    example: 12
                required:
                  - error
                  - message
                  - existing_subscription_id
        '422':
          $ref: '#/components/responses/ValidationException'
          description: The request failed validation.
        '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
    ValidationException:
      description: The request failed validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable validation overview.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
                description: Validation messages keyed by request field.
            required:
              - error
              - message
              - errors
    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

````