---
title: "Rotate a webhook subscription's secret"
method: POST
path: "/webhook-subscriptions/{subscription_id}/rotate-secret"
tags: ["webhooks"]
---

# Rotate a webhook subscription's secret

`POST /webhook-subscriptions/{subscription_id}/rotate-secret`

## Request

- Base URL: `https://api.pscrpt.com/v1`
- URL: `https://api.pscrpt.com/v1/webhook-subscriptions/{subscription_id}/rotate-secret`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.pscrpt.com/oauth/authorize`
    - Token URL: `https://api.pscrpt.com/oauth/token` scopes: `webhooks:write`

## Path parameters

- `subscription_id` string, required

## Headers

- `Idempotency-Key` string
- `If-Match` string
- `Postscript-Version` string, date

## Request body

- WebhookSecretRotateRequest
  - `previous_secret_expires_in_seconds` integer: Seconds the previous secret stays valid, from `0` (revoked immediately) to `86400` (24 hours, the default).

## Response `200`

The subscription, with its `secret`.

- WebhookSubscriptionEnvelope
  - `data` WebhookSubscription, required
    - `api_version` string, date, required
    - `created_at` string, date-time, required
    - `description` string, nullable, required
    - `event_types` string[], required: Topics listed by `GET /v1/webhook-topics`.
    - `id` string, required
    - `object` 'webhook_subscription', required
    - `secret` string, nullable, required: Signing secret (`whsec_…`). Returned only when the subscription is created or its secret rotated; null on every other read.
    - `status` 'enabled' | 'disabled' | 'auto_disabled', required: `auto_disabled`: every delivery attempt failed for 24 hours, with at least 20 failed attempts.
    - `updated_at` string, date-time, required
    - `url` string, uri, nullable, required
  - `meta` Meta, required
    - `as_of` string, date-time
    - `livemode` boolean, required
    - `page` PageMeta
      - `limit` integer, required
      - `next_cursor` string, nullable, required: Pass as `page[after]`. Null on the last page.
    - `request_id` string, required
    - `resolved_from` string: The merged-away profile ID the request addressed; `data` holds the survivor.
    - `revision` string, date, required

## Other responses

- `400`: Malformed input, an unknown parameter, an unsupported filter, sort, or expand, or a mistyped ID.
- `401`: Missing or invalid API key.
- `403`: The key lacks the required scope.
- `404`: No such resource in the authenticated property.
- `412`: The `If-Match` ETag is stale. Re-read the resource and retry.
- `429`: Rate limit exceeded.
- `500`: Internal error.
- `502`: Upstream provider failure.
- `503`: Temporarily unavailable.

## Changes

- **2026-10-19** `aee67d08657e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/changes/webhook-subscriptions/:subscription_id/rotate-secret/post.md)

---

[API](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta.md) - [All operations](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/revisions/882458ee1f36?raw)