Secret rotation

Each notification endpoint has exactly one active signing secret. Rotation replaces it: a new secret becomes active and the previous one stops signing. There is no overlap window on Tekmerion's side — so the safe cutover is one you run on your side, by accepting both secrets briefly while you roll the new one out.

How signing resolves

The signing secret is resolved at the moment Tekmerion executes a delivery, not when the notification was created.

• After you rotate, every newly executed delivery is signed with the new secret — including retries of earlier notifications and manual re-deliveries.
• The previous secret signs nothing once rotation commits.
• Your verifier MUST use the secret currently active for the endpoint and MUST NOT cache a superseded secret. See Signature verification.

Rotate with a dual-accept window

Because the new secret signs immediately while your verifier fleet may take time to pick it up, accept both secrets during the cutover.

1. Add the new secret alongside the old. Configure your verifier to accept a signature that validates under either the current secret or the new one. Do not remove the old secret yet.
2. Rotate the endpoint secret in Tekmerion. From this point, all new deliveries are signed with the new secret.
3. Confirm the new secret is live. Watch incoming deliveries until you see them validating under the new secret across all your verifier instances.
4. Drop the old secret. Once you are confident every delivery is signed with the new secret and your fleet is fully rolled out, stop accepting the old one. The window is closed.

Revoke on compromise

If a signing secret may be exposed, treat it as an emergency, not a planned rotation.

1. Rotate immediately. Replace the secret now; the compromised secret stops signing as soon as the rotation commits. Do not wait for a maintenance window.
2. Stop accepting the compromised secret at once. Unlike a planned rotation, do not keep a dual-accept window open for the exposed secret — accepting it leaves the window an attacker needs. Cut it the moment the new secret is live.
3. Re-verify in-flight deliveries. Any delivery still validating only under the old secret after revocation MUST be rejected.

A rejected delivery is not lost truth

A webhook is a side effect of a payment event, not the authoritative record of it. If a rotation race causes you to reject an otherwise valid delivery, you have not lost the payment fact.

• The same notification is retried as a new send of the same record once your verifier accepts the active secret again — deduplicate by delivery_record_id.
• Never treat a rejected or missing delivery as a failed payment. Reconcile canonical state through the API and the signed Proof-of-Payment artifact, correlating by payment_intent_id — never solely through receipt of a webhook. See Delivery semantics.