Webhook — Rotate HMAC Secret (admin)

POST /api/v1/admin/webhooks/:id/rotate-secret — 👤 Admin · permission config:write · Throttle: 10 req / hour

Generates a new cryptographically random HMAC signing secret for a WebhookEndpoint, persists it, and returns the plaintext value exactly once. The old secret is invalidated immediately — in-flight retries after rotation will use the new secret and fail subscriber-side verification until the subscriber updates their config.

Request

Path parameters

No body.

Headers

Throttle / permission

Response

201 Created — ApiResponseOf<WebhookSecretRotatedDto>

{
  "success": true,
  "data": {
    "secret": "a1b2c3d4e5f6...",
    "rotatedAt": "2026-06-22T14:00:00.000Z"
  }
}

Errors

Side effects

1. webhookEndpoint.findUnique({ where: { id } }) — 404 if missing.
2. Generate a new secret via generateSecret() (cryptographically random hex).
3. webhookEndpoint.update({ where: { id }, data: { secret } }) — old secret overwritten in place.
4. Return { secret, rotatedAt: updated.updatedAt.toISOString() }.
5. Audit log row via the controller-level AdminAuditInterceptor (request body redaction applies).

In-flight WebhookDelivery retries will read the new secret on next dispatch (the endpoint row is re-read per attempt), so a retry signed pre-rotation that hasn't fired yet will sign with the new value and fail subscriber verification until the subscriber updates their config.

Subscriber HMAC verification

Subscribers verify the X-Webhook-Signature header against the raw POST body using the secret distributed at endpoint creation / rotation:

X-Webhook-Signature: hmac-sha256-hex-string

The signature is computed server-side as signPayload(JSON.stringify(payload), endpoint.secret). Subscribers should compute the same and compare in constant time. A pre-rotation signature against a post-rotation secret will not match.

Code samples

curl -X POST 'https://api.bio.re/api/v1/admin/webhooks/wh-uuid/rotate-secret' \
  -H 'Cookie: admin_session=...' \
  -H 'X-CSRF-Token: ...'

type RotatedSecret = {
  secret: string;
  rotatedAt: string;
};

async function rotateWebhookSecret(endpointId: string, csrfToken: string): Promise<RotatedSecret> {
  const res = await fetch(`https://api.bio.re/api/v1/admin/webhooks/${endpointId}/rotate-secret`, {
    method: 'POST',
    credentials: 'include',
    headers: { 'X-CSRF-Token': csrfToken },
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    throw Object.assign(new Error(json?.error?.message ?? 'Rotate failed'), {
      code: json?.error?.code,
    });
  }
  return json.data;
}

Source