Rotate the signing key - Lumeus

cURL

# Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404.
curl --fail-with-body -sS -X POST 'https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/signing-key/rotate' \
  -H "Authorization: Bearer $LUMEUS_WEBHOOK_KEY" \
  -H 'Idempotency-Key: retry-0001-2026-10-22' \
  -H 'If-Match: "1"'

// Node 18+ (ES module)
// Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404.
const res = await fetch('https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/signing-key/rotate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_WEBHOOK_KEY}`,
    'Idempotency-Key': 'retry-0001-2026-10-22',
    'If-Match': '"1"',
  },
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

# Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404.
import json
import os

import requests

res = requests.post(
    "https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/signing-key/rotate",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_WEBHOOK_KEY']}", "Idempotency-Key": "retry-0001-2026-10-22", "If-Match": "\"1\""},
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "subscription_id": "00000000-0000-4000-8000-000000000000",
  "version": 2,
  "signing_version": 2,
  "previous_signing_version": 1,
  "previous_valid_until": "2026-10-23T09:15:04Z",
  "secret": "whsec_0000…"
}

POST

/

v1

/

subscriptions

/

{id}

/

signing-key

/

rotate

cURL

# Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404.
curl --fail-with-body -sS -X POST 'https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/signing-key/rotate' \
  -H "Authorization: Bearer $LUMEUS_WEBHOOK_KEY" \
  -H 'Idempotency-Key: retry-0001-2026-10-22' \
  -H 'If-Match: "1"'

// Node 18+ (ES module)
// Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404.
const res = await fetch('https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/signing-key/rotate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_WEBHOOK_KEY}`,
    'Idempotency-Key': 'retry-0001-2026-10-22',
    'If-Match': '"1"',
  },
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

# Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404.
import json
import os

import requests

res = requests.post(
    "https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/signing-key/rotate",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_WEBHOOK_KEY']}", "Idempotency-Key": "retry-0001-2026-10-22", "If-Match": "\"1\""},
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "subscription_id": "00000000-0000-4000-8000-000000000000",
  "version": 2,
  "signing_version": 2,
  "previous_signing_version": 1,
  "previous_valid_until": "2026-10-23T09:15:04Z",
  "secret": "whsec_0000…"
}

Authorizations

Authorization

string

header

required

Send Authorization: Bearer whk_…, a webhook key from the dashboard. Webhook keys belong to one network, so pick the server that matches the key. lum_ API keys are not accepted here (401).

Headers

Idempotency-Key

string

required

Required. Choose one key per change and resend it unchanged on a retry: the same key with the same request returns the first result instead of applying the change again, and the same key with a different request returns 409.

Required string length: 1 - 128

Example:

"retry-0001-2026-10-22"

If-Match

string

required

The ETag from GET /v1/subscriptions/{id}, for example "1" (the weak form W/"1" that some proxies produce is accepted too). A stale version returns 412; a missing header returns 428.

Pattern: ^(W/)?"[1-9][0-9]*"$

Example:

"\"1\""

Path Parameters

id

string<uuid>

required

Endpoint (subscription) ID from POST /v1/subscriptions or GET /v1/subscriptions. The example ID is a placeholder and answers 404: use your own.

Example:

"00000000-0000-4000-8000-000000000000"

Response

The new whsec_ secret, shown only in this response.

subscription_id

string<uuid>

required

version

integer

required

signing_version

integer

required

previous_signing_version

integer

previous_valid_until

string<date-time>

secret

string

New whsec_ value returned once on rotation, absent on retry or revocation.