# Rotate the signing secret

Issues a new signing secret and returns it **once**. For the next 24 hours every delivery is signed with
both the new and the previous secret (two `v1=` values in `X-Orderwerks-Signature`), so a receiver can
switch over without dropping deliveries.

Endpoint: POST /v1/webhooks/{webhookGuid}/rotate-secret
Version: 1.19
Security: ApiKey, ApiSecret, UserGuid, UserToken, SupplierGuid

## Security:

  - `ApiKey` (unknown)
    apiKey in header x-apiKey

  - `ApiSecret` (unknown)
    apiKey in header x-apiSecret

  - `UserGuid` (unknown)
    apiKey in header userGuid

  - `UserToken` (unknown)
    apiKey in header userToken

  - `SupplierGuid` (unknown)
    apiKey in header supplierGuid

## Path parameters:

  - `webhookGuid` (string, required)
    GUID of the webhook endpoint.

## Response 200:

  - `200` (unknown)
    The endpoint and its new secret.

## Response 200 fields (application/json):

  - `webhook` (object)
    An outbound webhook endpoint registered by the business. The signing secret is returned once, when the endpoint is created or its secret is rotated, and never again. Static header values are write-only; only their names are returned.

  - `webhook.guid` (string, required)

  - `webhook.name` (string, required)

  - `webhook.url` (string, required)
    HTTPS URL deliveries are posted to.

  - `webhook.active` (boolean, required)
    False pauses the endpoint; events that happen while it is paused are not queued.

  - `webhook.events` (array, required)
    Subscribed event types. See `GET /v1/webhook-events` for the list.

  - `webhook.workflow_triggers` (array, required)

  - `webhook.workflow_triggers.workflow_guid` (string, required)

  - `webhook.workflow_triggers.order_state_id` (integer, required)
    Order state id of the step (same ids as `Order.order_state_id`).

  - `webhook.header_names` (array)
    Names of the static headers sent with every delivery.

  - `webhook.api_version` (string, required)
    Payload version pinned when the endpoint was created (sent as `X-Orderwerks-Api-Version`).
    Example: 2026-10-27

  - `webhook.consecutive_failures` (integer)
    Failed attempts since the last 2xx. Any 2xx resets it; at 50 the endpoint is disabled.

  - `webhook.disabled_at` (string)
    Set when Orderwerks switched the endpoint off (failure streak or a `410 Gone`). Re-enable by updating `active` to true.

  - `webhook.disabled_reason` (string)

  - `webhook.last_delivery_at` (string)

  - `webhook.last_success_at` (string)

  - `webhook.previous_secret_expires_at` (string)
    While set, deliveries are also signed with the secret that was rotated out.

  - `webhook.created_at` (string)

  - `webhook.updated_at` (string)

  - `signing_secret` (string)

## Response 401:

  - `401` (unknown)
    Missing or invalid credentials.

## Response 401 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).

## Response 403:

  - `403` (unknown)
    The credentials are valid but the user lacks the access level this endpoint requires.

## Response 403 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).

## Response 404:

  - `404` (unknown)
    No resource with that GUID is visible to the authenticated supplier.

## Response 404 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).