Signed callbacks need a secret lifecycle

What the public implementation shows

Callback subscription creation returns a signing secret once, stores it under data protection, and exposes an explicit rotation endpoint.

Only the dispatch worker unprotects the secret to sign timestamp, event ID, and payload for delivery. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleA signature algorithm is only as operationally sound as the secret lifecycle around it.

The decision behind the mechanism

One-time disclosure limits later retrieval while rotation remains an auditable administrative action.

A permanently retrievable secret expands exposure; an instant uncoordinated rotation can invalidate in-flight deliveries. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Reveal the raw secret only at creation or rotation.
• Protect stored secret material with durable data-protection keys.
• Sign a canonical input that includes timestamp and event identity.
• Audit rotation and coordinate receiver cutover.

How the control should be operated

Subscribers need a documented verification input, clock policy, idempotency key, rotation procedure, and a way to distinguish old and new credentials during transition.

Callback authenticity remains maintainable after initial onboarding. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.