Rotate Webhook signing secret | ToAPIs Documentation

POST

/api/v1/webhook/rotate-secret

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

Behavior

Generates or replaces a given key's signing secret, which receivers use to verify callback signatures. Rotating does not enable callbacks. secret is returned only once in this response and cannot be re-issued by GET. If lost, rotate again.

The previous secret stays valid for 24 hours for verification overlap, with a single old-secret slot that consecutive rotations replace.

Writes reject deleted or scoped keys. Disabled, expired and exhausted model keys can still be managed. Rate limiting is shared with key-lifecycle writes: at most 10 write requests per user per minute. JSON is limited to 16384 bytes with a 10-second body read deadline.

Query parameters, unknown fields and duplicate JSON fields are rejected. Api_key_id must be explicit.

Authentication

Authorizationstringheaderrequired

Use the system access token Bearer YOUR_SYSTEM_ACCESS_TOKEN. Access is limited to your own account. Model keys are not accepted. X-User-Id is not required. There is no administrator or team bypass.

Request parameters

api_key_idintegerbodyrequired

Positive integer ID of your own ordinary model key, not the sk- secret or access token. JSON requires an integer; strings, null, omissions, and query parameters are rejected.

An invalid api_key_id returns 400; a missing or foreign key returns 404; secret management under mode=off returns 409 (code=16016); rate limiting returns 429.

Request examples

requestExample

curl --request POST \
  --url 'https://api.toapis.com/api/v1/webhook/rotate-secret' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"api_key_id":123}'

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "secret": "0000000000000000000000000000000000000000000000000000000000000000",
    "previous_secret_expires_at": null
  }
}

For the onboarding order and signature verification, see Get Webhook configuration.