Rotate the signing secret

Overview

Replace the signing secret with a new one.

Use this on a schedule, or if the secret may have been exposed. Update your verifier before the next delivery.

You'll need the subscription id.

Returns the new secret and the new hmac_secret_fingerprint. The old one stops working immediately.

Prerequisites

A Partner bearer token. See Authentication.
The subscription's id, from List your webhooks.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/partner/webhooks/{webhookSubscriptionId}/rotate-secret

Authentication

Partner token

Only partner users can call it; other tokens get 403.
Only your own partner's subscriptions: any other id, including another partner's, gets 404.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`webhookSubscriptionId`	path	integer	Yes	The subscription's id, from List your webhooks.

Request body

None.

Request payload

None. Send no body.

Response body

The payload is inside data.

Field	Type	Description
`data`	object	The subscription, with the new secret.
`data.id`	integer	The subscription's id (`webhookSubscriptionId`).
`data.partner_company_id`	integer	Your partner id.
`data.label`	string	Your name for the subscription.
`data.webhook_url`	string	Where deliveries are sent.
`data.events`	array of strings or null	The event filter. `null`: all immediate events. Always `null` on a batch subscription.
`data.payload_mode`	string	`full` (the review, who did it, and the history entry) or `minimal` (event name and ids only). Always `full` on a batch subscription.
`data.delivery_kind`	string	`immediate` (each event as it happens) or `batch` (one `cache_invalidation` ping per location per interval).
`data.batch_interval_hours`	integer or null	Hours between batches: `1`, `2`, `4`, `6` or `12`. `null` on an immediate subscription.
`data.delivery_label`	string	The delivery type in words: `immediate`, `hourly batch` or `every N hours`.
`data.last_batch_dispatched_at`	string or null	When the last batch was sent (ISO 8601). Set to the creation time for a new batch subscription; `null` on an immediate one.
`data.is_active`	boolean	Whether deliveries are being sent.
`data.hmac_secret_fingerprint`	string	The first 16 characters of the SHA-256 hash of the signing secret, so you can tell which secret is current. The secret itself is never returned here.
`data.last_succeeded_at`	string or null	When a delivery last succeeded (ISO 8601), or `null`.
`data.last_failed_at`	string or null	When a delivery last failed (ISO 8601), or `null`.
`data.last_failure_reason`	string or null	Why the last delivery failed, or `null`.
`data.consecutive_failure_count`	integer	Failed deliveries in a row since the last success.
`data.created_at`	string	When the subscription was created (ISO 8601).
`data.updated_at`	string	When it last changed (ISO 8601).
`data.hmac_secret`	string	The new signing secret. Shown here once; store it now.
`data.hmac_secret_warning`	string	A reminder that the previous secret no longer works.

Response payload

{
  "data": {
    "data": {
      "id": 3,
      "partner_company_id": 5,
      "label": "Production webhook",
      "webhook_url": "https://partner.example.com/hooks/sau",
      "events": [
        "review_pull_connected",
        "review_pull_disconnected",
        "usage.limit_reached"
      ],
      "payload_mode": "full",
      "delivery_kind": "immediate",
      "batch_interval_hours": null,
      "delivery_label": "immediate",
      "last_batch_dispatched_at": null,
      "is_active": true,
      "hmac_secret_fingerprint": "9c1d4e2a7b3f6058",
      "last_succeeded_at": "2026-06-16T10:27:30+00:00",
      "last_failed_at": null,
      "last_failure_reason": null,
      "consecutive_failure_count": 0,
      "created_at": "2026-06-16T10:23:23+00:00",
      "updated_at": "2026-06-20T09:00:00+00:00",
      "hmac_secret": "<hmac-secret>",
      "hmac_secret_warning": "Store this value securely — it will not be shown again. Update your verifier immediately; the previous secret is no longer accepted."
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Not a Partner token

{
  "message": "Only partner-admin users can manage webhook subscriptions.",
  "status": "error",
  "errors": []
}

404 Subscription not found

{
  "message": "Subscription not found.",
  "status": "error",
  "errors": []
}

Status	Meaning
`200`	The secret was replaced; store `hmac_secret` now.
`401`	The token is missing, expired or invalid.
`403`	The token isn't a Partner token.
`404`	No subscription with this id belongs to your partner.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/webhooks/3/rotate-secret" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'