Skip to content
Vocapable Developers

Rotate the target's signing secret

POST
/v1/webhook-targets/{target_id}/rotate-secret
curl --request POST \
  --url https://api.vocapable.com/v1/webhook-targets/example/rotate-secret \
  --header 'Authorization: Bearer <token>'

Mint a new signing secret, keeping the superseded one valid for 24 hours.

During the overlap every dispatch carries two v1= signatures - one per secret - so the receiver can be redeployed with the new key at any point inside the window, exactly like the endpoint rotation above (docs/04-api.md §5 signing).

An Idempotency-Key is honored so a retried rotate replays the first rotation’s minted secret rather than rotating twice and collapsing the previous secret’s overlap. The claim shares this request’s transaction with the rotation.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
target_id
required
Target Id
string

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
Any of:
string

Unique key for this request, so a retry replays the original result instead of repeating the work. Stored for 24 hours; a replayed response carries Idempotent-Replay: true. A UUID is the documented shape.

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
WebhookTargetSecretView

A summary plus the plaintext secret, when the answering call minted one.

object
id
required
Id
string
webhook_id
required
Webhook Id
string
description
required
Description
string
parameters
required
Parameters
object
key
additional properties
any
side_effect
required
Side Effect
string
timeout_seconds
required
Timeout Seconds
number
max_invocations_per_call
required
Max Invocations Per Call
integer
url
required
Url
string
status
required
Status
string
previous_secret_expires_at
required
Any of:
string format: date-time
created_at
required
Created At
string format: date-time
updated_at
required
Updated At
string format: date-time
secret
required
Any of:
string
Examplegenerated
{
  "id": "example",
  "webhook_id": "example",
  "description": "example",
  "parameters": {},
  "side_effect": "example",
  "timeout_seconds": 1,
  "max_invocations_per_call": 1,
  "url": "example",
  "status": "example",
  "previous_secret_expires_at": "2026-04-15T12:00:00Z",
  "created_at": "2026-04-15T12:00:00Z",
  "updated_at": "2026-04-15T12:00:00Z",
  "secret": "example"
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}