Skip to content
KataraKatara documentation

Rotate the webhook signing key

POST
/katara/v1/notification-webhooks/{id}/rotate
curl --request POST \
  --url https://api.katara.com/katara/v1/notification-webhooks/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "version": 1 }'

Returns a new secret once, revokes previous keys, and requires renewed ownership verification and explicit review. Already attempted deliveries remain bound to the old key and cannot move to the replacement.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Header Parameters

Section titled “Header Parameters”
X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
version
required
integer
>= 1
Examplegenerated
{
  "version": 1
}

Responses

Section titled “Responses”

200

Section titled “200”

Current subscription state. Responses are never cached.

Media typeapplication/json
object
subscription
required
object
id
required
string format: uuid
org_id
required
string format: uuid
environment_id
required
string format: uuid
reset_generation
required
integer
>= 1
mode
required
Allowed values: test live
destination
required
string format: uri
event_types
required
Array<string>
key_id
required
string format: uuid
state
required
Allowed values: pending verified active revoked
version
required
integer
>= 1
review_digest
required
string
/^sha256:[a-f0-9]{64}$/
created_at
required
string format: date-time
verified_at
string format: date-time
reviewed_at
string format: date-time
revoked_at
string format: date-time
verification_url
required
string format: uri
verification_document
required
object
profile
required
Allowed value: katara-notification-ownership/v1
subscription_id
required
string format: uuid
nonce
required
string
review_digest
required
string
/^sha256:[a-f0-9]{64}$/
challenge_expires_at
required
string format: date-time
signing_secret

32 random bytes encoded as unpadded base64url. Returned once on first create or rotation. Store privately; GET, list and create replay never return it.

string
Example
{
  "subscription": {
    "mode": "test",
    "state": "pending"
  },
  "verification_document": {
    "profile": "katara-notification-ownership/v1"
  }
}

400

Section titled “400”

Invalid request.

403

Section titled “403”

Current owner/admin recipient in a signed-in session required.

404

Section titled “404”

Subscription unavailable in the current scope.

409

Section titled “409”

Subscription changed or is in an incompatible state.