Skip to content

Verify Chronicle webhook signatures

A signed delivery lets the receiver prove that the Kernel sent a request and that nobody changed the body on the way. Signing is opt in per webhook: register it with WithSigning(WebhookSigningMode.Ed25519), as described in Signing. Verification does not replace authenticating the Kernel; use both.

A signed request carries these headers:

Header Contents
webhook-id The identifier of the delivery. It stays the same when the Kernel retries the same delivery.
webhook-timestamp The time of signing, in Unix seconds.
webhook-signature One or more space-separated signatures, each written v1a,<base64>.
Cratis-Key-Id The id of the key that produced the signature. Treat it as a hint only, never as a verification decision.

Chronicle follows the Standard Webhooks framing with asymmetric v1a signatures. The signed message is webhook-id, webhook-timestamp and the raw request body joined with dots (id.timestamp.body), signed with Ed25519 (RFC 8032) and encoded as Base64. Standard Webhooks publishes test vectors only for its HMAC v1 scheme, so Chronicle’s specifications pin the v1a format with an RFC 8032 key and a fixed message. HMAC v1 signing is not available yet.

The event store publishes the public keys of its signing key ring. Each key is whpk_ followed by the Base64 encoding of the 32-byte Ed25519 public key. The result includes the active key and, while a rotation overlaps, the previous key.

using Cratis.Chronicle;
using Cratis.Chronicle.Webhooks;
public class WebhookSignatureVerifierFactory(IEventStore eventStore)
{
public async Task<IWebhookSignatureVerifier> Create()
{
var keys = await eventStore.Webhooks.GetSigningKeys();
return new WebhookSignatureVerifier(keys);
}
}

View C# snippet source on GitHub

Receivers in other languages call the Kernel query GetWebhookSigningKeys on the Webhooks gRPC service, described under Signing keys. Load the keys when the receiver starts and keep them in memory or configuration. The Kernel does not push keys to receivers.

Verify the exact bytes the Kernel sent. Read the raw request body before any JSON parser touches it: a body that was deserialized and serialized again almost never matches byte for byte, and the signature then fails for a delivery that is genuine. Reject the request when verification fails and do not process it.

using Cratis.Chronicle.Webhooks;
app.MapPost("/chronicle/webhooks", async (HttpRequest request, IWebhookSignatureVerifier verifier) =>
{
using var buffer = new MemoryStream();
await request.Body.CopyToAsync(buffer);
var result = verifier.Verify(
request.Headers[WebhookSigningHeaders.Id],
request.Headers[WebhookSigningHeaders.Timestamp],
request.Headers[WebhookSigningHeaders.Signature],
buffer.ToArray());
if (!result.IsValid)
{
return Results.Unauthorized();
}
// The body is authentic: deserialize buffer and process the events.
return Results.Ok();
});

View C# snippet source on GitHub

A delivery is valid when any v1a signature in the header verifies under any configured key. The verifier also rejects a timestamp more than five minutes away from the receiver’s clock, in either direction, so keep the receiver’s clock synchronized. Signatures of other versions are ignored.

When the key ring rotates, the Kernel signs each delivery with both the new and the previous key until the overlap ends, and the header carries both signatures. A receiver that has either key configured accepts the delivery. After a rotation, fetch the keys again and keep the old key until its OverlapEndsAt has passed. When you build the verifier from the keys the event store returns, it applies OverlapEndsAt itself and stops accepting an overlap key once that time has passed. Keys disappear from the query once the overlap ends.

Refresh the keys when verification fails for a delivery whose Cratis-Key-Id you do not know, then verify once more. Never skip verification because a key id is unknown.

The timestamp tolerance limits how long a captured request stays usable, but it does not make a delivery single use. Also record the webhook-id values you have processed and ignore repeats, as described in Webhook receivers. A replay of events from Chronicle is a new delivery with a new webhook-id, so the event sequence number remains the key for deduplicating the effect itself.

Any language with an Ed25519 implementation can verify a delivery:

  1. Reject the request when webhook-id, webhook-timestamp or webhook-signature is missing, or when the timestamp is more than five minutes from now.
  2. Build the message as webhook-id, webhook-timestamp and the raw body, joined with dots.
  3. Remove the whpk_ prefix from each public key and Base64-decode it to 32 bytes.
  4. Split webhook-signature on spaces, keep entries that start with v1a,, and Base64-decode the rest.
  5. Accept the request when any signature verifies under any key. Compare in constant time where your library requires it.