Rotate signing secrets

Before you rotate

You are an authorised company administrator using a dashboard session for the endpoint’s company. A company API key or SDK cannot perform this action. Prepare secret-manager access and a receiver deployment plan; new attempts change immediately, so coordinate the maintenance window.

Rotate in the dashboard

Rotate from Developer → Webhooks → Rotate signing secret in the Kua dashboard. This requires the company’s settings permission and a fresh identity confirmation for webhook.secret.rotate. It is a dashboard session action; API keys and the SDK cannot rotate signing secrets.

Review the endpoint, rotate, and save the new secret shown once. New attempts use the new secret immediately. Update the receiver before expecting successful delivery; there is no promised overlap or grace period for the old secret. Inspect delivery status and recover exhausted events after the receiver is updated. If the rotation response is lost, the new secret may already be active; check the receiver and dashboard before deliberately rotating again. Never put signing secrets in logs, support messages or recovery reasons.

Verify and recover

Check a new ping and inspect its delivery history and your durable receiver inbox. A successful rotation dialog is not proof that the receiver has the new secret. Do not log either secret while investigating. Keep event-ID deduplication across the deployment; replaying an old event signs it with the current secret.

If receiver configuration cannot be updated, stop dependent processing and involve the authorised administrator; do not assume reverting a local environment variable restores the old server secret. If the one-time response was lost, deliberately rotating again creates another credential change. Inspect state and plan that change before repeating it.

Done when: the current secret is stored, the receiver accepts a new signed attempt, the same event remains deduplicated and any exhausted deliveries are reconciled through recovery.