Rotate HMAC secret

Overview

Generate a new 256-bit HMAC secret and atomically replace the stored ciphertext + fingerprint. The OLD secret immediately stops verifying. You must update the partner's verifier in lock-step. The endpoint returns the new raw secret ONCE in hmac_secret. No request body required.

Prerequisites

A bearer token. Callable with Partner tokens.
The webhookSubscriptionId of the record you are targeting.

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

Requires a bearer token in the Authorization: Bearer <bearer-token> header.
Who can call it: Partner tokens.
findCallerSubscription enforces bundle_id === 1 and scopes by partner_company_id (404 if not owned).

Rate limit

No rate limit.

Path parameters

Parameter	Type	Required	Description
`webhookSubscriptionId`	integer	Required	Digits only.

Request body

No body.

{}

Response

data.hmac_secret (string) — new raw secret, shown ONCE
data.hmac_secret_warning (string) — notes the previous secret is no longer accepted

200 Success · `200`

{
  "data": {
    "data": {
      "id": 3,
      "partner_company_id": 5,
      "label": "dummy_label",
      "webhook_url": "https://dummy.url/webhook",
      "events": null,
      "payload_mode": "full",
      "delivery_kind": "batch",
      "batch_interval_hours": 4,
      "delivery_label": "every 4 hours",
      "last_batch_dispatched_at": "2026-06-16T10:25:29+00:00",
      "is_active": true,
      "hmac_secret_fingerprint": "011d12e18d77edfb",
      "last_succeeded_at": null,
      "last_failed_at": null,
      "last_failure_reason": null,
      "consecutive_failure_count": 0,
      "created_at": "2026-06-16T10:25:29+00:00",
      "updated_at": "2026-06-16T10:26:29+00:00",
      "hmac_secret": "whsec_DUMMYsecretFORdocsONLYdoNOTuse00000000",
      "hmac_secret_warning": "Store this value securely — it will not be shown again. Update your verifier immediately; the previous secret is no longer accepted."
    }
  }
}

Errors

Status	Meaning
`401`	The bearer token is missing, expired or invalid
`404`	Returned if not owned
`500`	Unexpected server error

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/webhooks/123/rotate-secret" \
  --header 'Authorization: Bearer {{bearerToken}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}'

Updated 8 days ago

Did this page help you?