Roll a webhook endpoint's signing secret

post/v1/webhook-endpoints/{webhook_endpoint_id}/roll-secret

Issues a new signing secret, returned once. For overlap_hours (default 24, max 168) the previous secret stays valid and deliveries carry signatures from both the new and the previous secret, so receivers can switch without dropping events: X-Vojo-Signature: t=<unix>,v1=<new>,v1=<previous>. Receivers accept a delivery if any v1 matches any secret they hold. overlap_hours: 0 ends the previous secret immediately. An endpoint whose secret predates signing gets no overlap: it goes straight to signed with the new secret. A roll inside a live overlap keeps the original previous secret and extends the overlap to the later of the two end times, never shortening it (the secret in between stops at once), so to roll twice on purpose, wait for the overlap to end or send overlap_hours: 0. A portal roll has no overlap. The full verification rules are in Receive webhooks.

curl -X POST "https://api.vojo-media.com/v1/webhook-endpoints/$WEBHOOK_ENDPOINT_ID/roll-secret" \
  -H "Authorization: Bearer $VOJO_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

const { data, error } = await api.POST("/v1/webhook-endpoints/{webhook_endpoint_id}/roll-secret", {
  params: { path: { webhook_endpoint_id: webhookEndpointId } },
  body: {
    overlap_hours: 24,
  },
});
if (error) throw new VojoApiError(error);

Response 200

{
  "data": {
    "id": "cm1whe4r8t0001y2u6i9o3p5wa",
    "name": "Billing system",
    "url": "https://hooks.example.com/vojo",
    "enabled_events": [
      "verification.score",
      "wrapper.ready"
    ],
    "status": "active",
    "signed": true,
    "created_at": "2026-10-21T09:00:00Z",
    "updated_at": null,
    "secret": "whsec_8Lm2nB5vC9xZ1qW4eR7tY3uI"
  },
  "meta": {}
}

Access

Authentication: Secret key or OAuth access token.
Scope: webhooks:write
User permission: developerAccess

Path parameters

webhook_endpoint_idstringRequired

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
Vojo-Versionstring
Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.
date

Request body

overlap_hoursinteger
0 to 168
Default 24

Response 200

dataobjectRequired
A webhook endpoint plus its signing secret, returned only on create and roll.
Show 9 fields
- idstringRequired
- namestringRequired
- urlstringRequired
  HTTPS only.
  uri
- enabled_eventsarray of stringRequired
  Event types from the webhook catalogue (event reference). Unknown types return 422.
- statusstringRequired
  disabled = turned off by Vojo after repeated delivery failures; set active to resume.
  One of active, inactive, disabled
- signedbooleanRequired
  False only for legacy endpoints whose secret predates signing; roll the secret to start signing.
- created_atstringRequired
  date-time
- updated_atstring or nullRequired
  date-time
- secretstringRequired
  Signing secret. Shown only in this response.
metaobjectRequired

Response headers

Vojo-Versionstring
The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.
RateLimitstring
IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.
RateLimit-Policystring
IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.

Errors

Every error is application/problem+json. Branch on its code.

401
Missing, invalid, expired or revoked credential.
403
The caller is authenticated but not allowed: missing scope (insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied).
404
The resource does not exist, or belongs to another organisation. Cross-org ids always 404, never 403.
429
Rate limit exceeded for this principal. Back off for Retry-After seconds.
500
Unexpected server failure.