VocalDocscontracts 1.65.0

Rotate the secret of a pre-call hook

POST /v1/pre-call-hooks/{hook_id}/rotate-secret

PropertyValue
Operationrotate_pre_call_hook_secret
GroupPre-call hooks
Scopehooks:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited dispatch.pre_call_hook.rotate_secret (mutation)
Released in1.52.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Mints a new secret and answers it once (1.52.0). The previous one keeps signing beside it for previous_secret_expires_in_s (86,400 by default), every request in the window carrying two v1 values, the new one first; rotating again retires the oldest. A replay under the same Idempotency-Key rotates nothing and answers secret null.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the hooks:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/pre-call-hooks/pch_.../rotate-secret" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Parameters

NameInTypeRequiredDescription
hook_idpathPreCallHookIdyesThe id of a pre-call hook: pch_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: PreCallHookSecretRotateRequest.

FieldTypeRequiredDescription
previous_secret_expires_in_sintegernoHow long the previous secret keeps signing beside the new one, 0 to 604,800 seconds; 86,400 when omitted.

Responses

StatusContent typeShapeError codes
200application/jsonPreCallHookSecretRotation
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 200 answer

The shape is PreCallHookSecretRotation.

FieldTypeRequiredDescription
object"pre_call_hook_secret_rotation"yes
previous_secret_expires_atTimestamp or nullyes
previous_secret_hintstring or nullyes
rotated_atTimestampyes
secretPreCallHookSecret or nullyesThe new secret once; null on a replay, which rotated nothing.
secret_hintstringyes