> ## Documentation Index > Fetch the complete documentation index at: https://docs.powerdialer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rotate a webhook signing secret > Generate a replacement signing secret for a v2 receiver, including the first secret you configure after creating a subscription. Requires `webhooks:manage` and the owning credential. There is no request body. The response exposes `signingSecret` once and reports `active:false`. Rotation immediately replaces the old secret, pauses the subscription and clears verification. Store the new value in your receiver's secret manager, update signature verification, then call the verification endpoint to resume delivery. Queued deliveries encountered while inactive can become cancelled and need explicit replay. API-key rotation in Developers is separate and does not change this secret. This operation does **not** use an idempotency receipt. Never automatically retry it, even if you supply an `Idempotency-Key`. If the response is lost, explicitly rotate again, save that new secret and reverify before relying on delivery. `404 not_found` requires checking the subscription and originating credential; a `503` needs service investigation before deliberate recovery. See [signing and setup](/guides/webhooks#register-and-verify-a-receiver). ## OpenAPI ````yaml /api/openapi.json post /webhooks/{id}/rotate-secret openapi: 3.1.0 info: title: PowerDialer API v2 version: 2.0.0 description: >- Connect your CRM, sales workspace or reporting tools to PowerDialer using scoped API keys. Manage contacts and calling lists, read call evidence and analytics, and receive signed events. All example records and IDs are synthetic; replace them with values from your workspace. Shared-key v1 is retired. API availability was verified on 2026-10-08; see /availability for historical data coverage. Legacy outbound webhooks use a separate contract. servers: - url: https://api.migration.powerdialer.ai/api/public/v2 description: Production API v2; availability verified on 2026-10-08. security: - ApiKey: [] tags: - name: Authentication - name: Contacts - name: Calling lists - name: Imports - name: Calls - name: Synchronization - name: Analytics - name: Webhooks - name: Webhook deliveries - name: Incoming webhook payloads paths: /webhooks/{id}/rotate-secret: post: tags: - Webhooks summary: Rotate a webhook signing secret description: >- Generate a replacement signing secret for a v2 receiver, including the first secret you configure after creating a subscription. Requires `webhooks:manage` and the owning credential. There is no request body. The response exposes `signingSecret` once and reports `active:false`. Rotation immediately replaces the old secret, pauses the subscription and clears verification. Store the new value in your receiver's secret manager, update signature verification, then call the verification endpoint to resume delivery. Queued deliveries encountered while inactive can become cancelled and need explicit replay. API-key rotation in Developers is separate and does not change this secret. This operation does **not** use an idempotency receipt. Never automatically retry it, even if you supply an `Idempotency-Key`. If the response is lost, explicitly rotate again, save that new secret and reverify before relying on delivery. `404 not_found` requires checking the subscription and originating credential; a `503` needs service investigation before deliberate recovery. See [signing and setup](/guides/webhooks#register-and-verify-a-receiver). operationId: postWebhooksByIdRotateSecret parameters: - name: id in: path required: true schema: type: string format: uuid description: >- Subscription UUID returned by registration or listing. It must belong to the credential making this request. example: 00000000-0000-4000-8000-000000000001 responses: '200': description: >- A one-time replacement signing secret. The receiver is paused and must be verified again. headers: X-Request-Id: schema: type: string format: uuid RateLimit-Limit: schema: type: integer RateLimit-Remaining: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/WebhookSecret' example: id: 00000000-0000-4000-8000-000000000001 signingSecret: example-signing-secret-replace-with-the-returned-value active: false default: description: >- Error. 400 invalid request; 401 invalid credential; 403 insufficient access; 404 not found; 409 state/idempotency conflict; 413 size limit; 422 verification failure; 429 rate limit (Retry-After seconds); 503 temporary service failure. headers: Retry-After: schema: type: integer X-Request-Id: schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: API key is invalid, expired or revoked requestId: 00000000-0000-4000-8000-000000000004 x-codeSamples: - lang: bash label: cURL source: >- # Replace example resource IDs and ownerId with values from your workspace. : "${POWERDIALER_API_KEY:?Set POWERDIALER_API_KEY to your scoped API key}" curl --request POST \ --url 'https://api.migration.powerdialer.ai/api/public/v2/webhooks/00000000-0000-4000-8000-000000000001/rotate-secret' \ --header "Authorization: Bearer $POWERDIALER_API_KEY" components: schemas: WebhookSecret: type: object properties: id: type: string format: uuid description: Subscription ID. signingSecret: type: string description: >- New plaintext signing secret, returned once. Save it securely in your receiver before verifying. It is different from your API key. active: const: false description: >- Always false after rotation. Verify the receiver again to resume delivery. required: - id - signingSecret - active examples: - id: 00000000-0000-4000-8000-000000000001 signingSecret: example-signing-secret-replace-with-the-returned-value active: false Error: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code. message: type: string description: Human-readable explanation. requestId: type: string format: uuid description: Request identifier to include when investigating a failure. details: type: array items: type: object properties: path: type: string message: type: string required: - path - message description: Validation errors, when available. required: - code - message - requestId required: - error examples: - error: code: insufficient_scope message: Requires contacts:read requestId: 00000000-0000-4000-8000-000000000004 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: pd__. description: >- Issued in Developers. Workspace/owner/scopes come from credential, never acting-user headers. API keys cannot manage API credentials. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.