---
title: "Rotate a voice number's callback secret"
method: POST
path: "/v3/channels/voice/{number}/rotate-secret"
tags: ["Channels", "Voice"]
---

# Rotate a voice number's callback secret

`POST /v3/channels/voice/{number}/rotate-secret`

## Request

- Base URL: `https://api.sent.dm`
- URL: `https://api.sent.dm/v3/channels/voice/{number}/rotate-secret`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Generates a new signing secret for the questions Sent sends to this number's callback URL and returns it. The previous secret stops signing immediately, so update your backend before the next call reaches it. The number is the E.164 value in the path with the plus sign URL-encoded (`%2B`).

With `sandbox: true` a secret is generated and returned with `202`, and nothing is written.

## Path parameters

- `number` string, required

## Headers

- `Idempotency-Key` string
- `x-profile-id` string, uuid

## Request body

- SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsRotateVoiceSecretRequest: Base request for mutation operations (POST, PUT, PATCH) with sandbox mode support
  - `sandbox` boolean: Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution

## Response `200`

The new secret. The old one no longer signs anything

- SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceSecretResponse: Standard API response envelope for all v3 endpoints
  - `success` boolean: Indicates whether the request was successful
  - `data` SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceSecretResponse: A freshly rotated callback signing secret
    - `callback_secret` string: The new whsec_ secret. The previous one stopped signing the moment this was returned, so update your backend before the next call reaches it. Shown once.
  - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information
    - `code` string: Machine-readable error code (e.g., "RESOURCE_001")
    - `message` string: Human-readable error message
    - `details` object, nullable: Additional validation error details (field-level errors)
    - `doc_url` string, nullable: URL to documentation about this error
  - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata
    - `request_id` string: Unique identifier for this request (for tracing and support)
    - `timestamp` string, date-time: Server timestamp when the response was generated
    - `version` string: API version used for this request

## Other responses

- `202`: Sandbox: a secret that was not stored
- `400`: Invalid number, or the number has never had voice turned on
- `401`: Unauthorized - Invalid API credentials
- `403`: Forbidden
- `500`: Internal server error

## Changes

- **2026-10-16** `6c829543a93e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/channels/voice/:number/rotate-secret/post.md)

---

[API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)