Rotate Signing Secret | Captain Docs

import os
import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
SECRET_FILE = "captain-webhook.env"
ENDPOINT_ID = "whe_3f9a1c7e5b2d4a6c8e0f1a2b"
def save_webhook_secret(secret):
    """Write the secret to an env file only this user can read. The receiver loads it as CAPTAIN_WEBHOOK_SECRET."""
    fd = os.open(SECRET_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    os.fchmod(fd, 0o600)  # also tightens a file that already existed
    with os.fdopen(fd, "w") as secret_file:
        secret_file.write(f"CAPTAIN_WEBHOOK_SECRET={secret}\n")
response = requests.post(
    f"{BASE_URL}/v2/webhooks/endpoints/{ENDPOINT_ID}/rotate-secret",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30.0,
)
response.raise_for_status()
data = response.json()
save_webhook_secret(data["secret"])
print(f"Saved the new signing secret to {SECRET_FILE}")
print(f"The old secret keeps working for {data['previous_secret_valid_for_hours']} hours")

Create a new signing secret for an endpoint. The new secret is returned only in this response. For the next 24 hours every request carries two signatures, one with the old secret and one with the new, so the receiver keeps verifying whichever secret it holds. Deploy the new secret within that window.

Path parameters

endpoint_idstringRequired

The endpoint’s id (whe_...).

Response

Successful Response

endpoint_idstring

secretstring

The new signing secret (whsec_...). Returned only in this response.

previous_secret_valid_for_hoursinteger

How long requests stay signed with the old secret as well (24).

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

503

Service Unavailable Error