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

# Rotate signing secret

Generate a new signing secret for this subscription, replacing the previous one. Use this if your existing secret has been exposed or you've simply lost it.

The new `signingSecret` is only returned in this response — store it immediately.

Deliveries made after rotation are signed with the new secret, and retries of earlier failed deliveries are re-signed with it too. Accept a delivery that verifies against **either** the new or the previous secret for at least the next 24 hours after rotating, then discard the previous one.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location --request POST 'https://www.headout.com/api/public/v2/event-subscriptions/whsub_01j9z8x7v6w5u4t3s2r1q0p9o8/rotate-secret/' \
--header 'Headout-Auth: <YOUR_API_KEY>'
```

```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "signingSecret": "dingdong_ISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0-P0A"
}
```

```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "timestamp": 1786441790000,
  "traceId": "aad8e04d4cb6d466",
  "traceTokenOriginal": "E33C34A07812483E9DE02FF272F48A34",
  "error": {
    "code": "CAL-P0008",
    "message": "No event subscription found for this ID"
  }
}
```


## OpenAPI

````yaml POST /api/public/v2/event-subscriptions/{id}/rotate-secret/
openapi: 3.1.0
info:
  title: Headout API Docs - Common v2
  version: 0.0.1
servers:
  - url: https://www.headout.com
    description: Production server
  - url: https://www.sandbox-headout.com
    description: Sandbox server
security: []
paths:
  /api/public/v2/event-subscriptions/{id}/rotate-secret/:
    post:
      tags:
        - Event Subscriptions
      summary: Rotate signing secret
      operationId: v2RotateEventSubscriptionSecret
      parameters:
        - $ref: '#/components/parameters/eventSubscriptionId'
      responses:
        '200':
          description: >-
            New signing secret generated for this subscription. This is the only
            time the new `signingSecret` value is returned — store it now, it
            cannot be retrieved again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotatedSecret'
        '404':
          description: No event subscription found for this ID
      security:
        - apiKeyAuth: []
components:
  parameters:
    eventSubscriptionId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: >-
        Identifier of the event subscription, e.g. `whsub_01j...`. Returned as
        `id` from Create event subscription and List event subscriptions.
  schemas:
    RotatedSecret:
      type: object
      properties:
        signingSecret:
          type: string
          description: >-
            The new signing secret. Only returned here — store it immediately,
            as it replaces the previous secret for verifying future deliveries
            and cannot be retrieved again.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Headout-Auth

````

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