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

# Rotate the signing secret

> Generates a fresh signing secret and returns it ONCE. The old secret is immediately invalidated — the next event delivery is signed with the new secret. Store the new value securely; it cannot be retrieved later.

Supply an `Idempotency-Key` header to safely retry on network errors — replays under the same key return the original rotation response rather than minting a fresh secret. Replays against a different `public_id` under the same key return `409 idempotency_conflict`.



## OpenAPI

````yaml /openapi-app.json post /webhooks/{public_id}/rotate-secret
openapi: 3.1.0
info:
  description: Programmatic access to your Qubrics email infrastructure.
  title: Qubrics API
  version: 1.0.0
servers:
  - description: API v1
    url: https://app.qubrics.com/api/v1
security:
  - bearerAuth: []
  - oauth2: []
paths:
  /webhooks/{public_id}/rotate-secret:
    post:
      tags:
        - Webhooks
      summary: Rotate the signing secret
      description: >-
        Generates a fresh signing secret and returns it ONCE. The old secret is
        immediately invalidated — the next event delivery is signed with the new
        secret. Store the new value securely; it cannot be retrieved later.


        Supply an `Idempotency-Key` header to safely retry on network errors —
        replays under the same key return the original rotation response rather
        than minting a fresh secret. Replays against a different `public_id`
        under the same key return `409 idempotency_conflict`.
      operationId: managementRotateWebhookSecret
      parameters:
        - in: path
          name: public_id
          required: true
          schema:
            description: Webhook public ID
            type: string
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            description: >-
              Client-chosen unique key to safely retry the request. Cached for
              24h per (team, endpoint, key). Different target `public_id` under
              the same key returns 409 idempotency_conflict.
            example: webhooks-rotate-20260424-001
            maxLength: 255
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionWithSecretResponse'
          description: Subscription with new signing secret
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Subscription not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `Idempotency-Key` was replayed against a different webhook
            (`idempotency_conflict`).
      security:
        - bearerAuth: []
        - oauth2:
            - webhook.manage
components:
  schemas:
    WebhookSubscriptionWithSecretResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - properties:
            data:
              $ref: '#/components/schemas/WebhookSubscriptionWithSecret'
            meta:
              $ref: '#/components/schemas/ResponseMeta'
          required:
            - data
          type: object
      unevaluatedProperties: false
    ApiError:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              description: Machine-readable error code
              enum:
                - invalid_parameter
                - missing_parameter
                - authentication_required
                - insufficient_permissions
                - not_found
                - conflict
                - limit_exceeded
                - idempotency_conflict
                - payload_too_large
                - validation_error
                - rate_limit_exceeded
                - service_unavailable
                - internal_error
              example: invalid_parameter
              type: string
            doc_url:
              description: Link to relevant documentation
              type: string
            errors:
              description: >-
                Accumulated per-field issues for validation errors. Only present
                on 400/422 responses.
              items:
                $ref: '#/components/schemas/ApiErrorDetail'
              type: array
            message:
              description: Human-readable error description
              type: string
            param:
              description: The parameter that caused the error
              type: string
            retryable:
              description: >-
                Whether the caller may safely retry this request. 4xx are
                typically false (except 429); 5xx are typically true.
              example: false
              type: boolean
          required:
            - code
            - message
            - retryable
          type: object
        meta:
          additionalProperties: false
          properties:
            request_id:
              example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx
              type: string
          required:
            - request_id
          type: object
        ok:
          enum:
            - false
          type: boolean
      required:
        - ok
        - error
        - meta
      type: object
    SuccessEnvelope:
      properties:
        meta:
          additionalProperties: {}
          properties: {}
          type: object
        ok:
          enum:
            - true
          type: boolean
      required:
        - ok
        - meta
      type: object
    WebhookSubscriptionWithSecret:
      additionalProperties: false
      properties:
        created_at:
          description: ISO 8601 creation timestamp
          example: '2026-04-23T09:12:00Z'
          type: string
        enabled:
          description: When false, no events are delivered to this subscription.
          example: true
          type: boolean
        event_types:
          description: Event types this subscription receives.
          example:
            - message.bounced
            - message.received
          items:
            description: >-
              Event types a webhook may subscribe to. `sendmux.test` is accepted
              so you can verify end-to-end delivery via POST
              /webhooks/{id}/test.
            enum:
              - message.delivered
              - message.bounced
              - message.complained
              - message.rejected
              - message.delivery_delayed
              - message.received
              - message.received.spam
              - calendar.changed
              - sendmux.test
            example: message.bounced
            type: string
          type: array
        failing:
          description: >-
            True when the 24-hour retry window has been exhausted for this
            subscription. Reset by updating the subscription (e.g. fixing the
            URL) and re-enabling.
          example: false
          type: boolean
        filters:
          $ref: '#/components/schemas/WebhookFilters'
        id:
          description: Webhook public ID
          example: whk_clxxxxxxxxxxxxxxxxxxxxxxxxx
          type: string
        name:
          description: >-
            Optional human-friendly label used in dashboard list/detail pages.
            May be `null` for subscriptions created without a name.
          example: Acme inbound forwarder
          type:
            - string
            - 'null'
        secret:
          description: >-
            Signing secret for both webhook signature versions.
            X-Qubrics-Signature signs the exact body bytes.
            X-Qubrics-Signature-V2 contains v1=<hex HMAC-SHA256> and signs
            X-Qubrics-Timestamp (Unix seconds), a full stop, then the exact body
            bytes. The X-Sendmux-Signature, X-Sendmux-Signature-V2 and
            X-Sendmux-Timestamp headers carry the same values and remain
            supported indefinitely. Check timestamp freshness and compare
            signatures in constant time before parsing the body. Store this
            secret securely. It is returned only on creation and rotation. Use
            POST /webhooks/{id}/rotate-secret to issue a new one.
          example: whsec_a9f3c2…
          type: string
        updated_at:
          description: ISO 8601 last-modified timestamp
          example: '2026-04-23T09:12:00Z'
          type: string
        url:
          description: HTTPS endpoint that receives signed event POSTs.
          example: https://hooks.acme.com/sendmux
          format: uri
          type: string
      required:
        - id
        - name
        - url
        - event_types
        - filters
        - enabled
        - failing
        - created_at
        - updated_at
        - secret
      type: object
    ResponseMeta:
      additionalProperties: false
      properties:
        request_id:
          example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx
          type: string
      required:
        - request_id
      type: object
    ApiErrorDetail:
      additionalProperties: false
      properties:
        code:
          description: >-
            Machine-readable issue code from the validator (e.g. zod issue
            code).
          example: invalid_string
          type: string
        field:
          description: Dot-path of the offending request field.
          example: recipient.email
          type: string
        message:
          description: Human-readable issue description.
          type: string
      required:
        - field
        - code
        - message
      type: object
    WebhookFilters:
      additionalProperties: false
      description: Optional delivery scope. Empty mailbox_ids means all team mailboxes.
      properties:
        mailbox_ids:
          description: >-
            Mailbox public IDs to receive events for. Empty means all mailboxes
            in the team.
          example:
            - mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx
          items:
            type: string
          type: array
      required:
        - mailbox_ids
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: API Key
      description: >-
        Qubrics API key. Use a root API key for Management API routes, or a
        mailbox credential for Mailbox API routes. Obtain keys from the
        dashboard under API Keys.
      scheme: bearer
      type: http
    oauth2:
      description: >-
        Use the authorisation-code flow with S256 PKCE and
        resource=https://qubrics.com/api. The user selects the team, API access
        and mailboxes during consent. OAuth access tokens authenticate HTTP API
        requests; use separate credentials for SMTP and IMAP.
      flows:
        authorizationCode:
          authorizationUrl: https://app.qubrics.com/oauth/authorize
          refreshUrl: https://app.qubrics.com/oauth/token
          scopes:
            analytics.*: All analytics operations
            analytics.read: View key usage analytics and verification logs
            billing.*: All billing operations
            billing.auto_topup: Configure auto top-up settings
            billing.read: View balance, transactions, invoices
            billing.topup: Purchase balance top-ups
            calendar.read: Read calendars and events in this mailbox
            calendar.write: >-
              Create calendars and create, edit and delete events in this
              mailbox
            domain.*: All domain operations
            domain.create: Add sending domains
            domain.delete: Remove domains
            domain.read: List/view domains and DNS status
            domain.verify: Trigger domain verification
            email.receive: Authorise email reception
            email.send: Send email through the HTTP API
            key.*: All key management operations
            key.create: Create new API keys (both root and mailbox)
            key.read: List/view API keys and their metadata
            key.revoke: Revoke API keys
            key.rotate: Rotate API keys
            logs.*: All log operations
            logs.read: View delivery logs
            mailbox.admin.*: All mailbox admin operations
            mailbox.admin.create: Create mailboxes (admin-level)
            mailbox.admin.delete: Delete mailboxes (admin-level)
            mailbox.admin.manage: Manage all mailbox settings
            mailbox.admin.read: List/view mailboxes (admin-level)
            mailbox.drafts.write: Create and edit saved mailbox drafts
            mailbox.read: Read mailbox contents (folders, messages)
            mailbox.settings.update: Update own mailbox settings (signature, auto-reply)
            provider.*: All provider operations
            provider.create: Add email provider accounts (Google, Microsoft, SMTP)
            provider.delete: Remove provider accounts
            provider.read: List/view provider accounts and connection status
            provider.update: Update provider settings, refresh tokens
            routing.*: All routing operations
            routing.create: Create delivery groups
            routing.delete: Remove delivery groups
            routing.read: List/view delivery groups and routing rules
            routing.update: Update delivery group configuration
            team.*: All team operations
            team.members.invite: Invite team members
            team.members.remove: Remove team members
            team.members.roles: Change member roles
            team.read: View team settings and members
            team.update: Update team settings
            webhook.*: All webhook operations
            webhook.create: Create webhook subscriptions
            webhook.delete: Delete webhook subscriptions
            webhook.manage: Rotate signing secret + send test events
            webhook.read: List/view webhook subscriptions
            webhook.update: Update webhook URL, event types, enabled flag
          tokenUrl: https://app.qubrics.com/oauth/token
      type: oauth2

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.