Verify with a Cimento SDK
Install the SDK. Neither has any dependencies.whsec_... value Cimento shows once when you create the endpoint.
- it verifies the signature over the body exactly as it arrived;
- it rejects a request whose
webhook-timestampis more than five minutes from your server’s time; - it accepts a request signed with either secret while you rotate;
- it returns the event with
datatyped for the event’stype. See Reading events with an SDK.
Handler also answers Cimento: 204 when your function returns nil, 500 when it returns an error, and 401 or 400 for a request that doesn’t verify. The TypeScript example does the same by hand for a plain Node server.
If your TypeScript server speaks the Fetch API, as Cloudflare Workers, Deno, Bun, Hono and Next.js route handlers do, fetchHandler answers for you in the same way:
TypeScript
Go
github.com/cimento-ai/cimento-sdk/go/webhooks on pkg.go.dev. Needs Go 1.26 or newer.TypeScript
@cimento/webhooks on npm. Needs Node 22 or newer, or any runtime with Web Crypto.What is signed
Each request has three headers:
The signature is an HMAC-SHA256 of the id, the timestamp and the request body, joined by full stops:
Signed content
whsec_ prefix removed and the rest decoded from base64.
Verify with a Standard Webhooks library
For a language Cimento has no SDK for, Standard Webhooks has libraries for Python, Java, Ruby, PHP, C#, Rust and others. Each takes your secret, the raw body and the headers, and throws or returns an error when the request doesn’t verify.Python
webhook-timestamp is more than five minutes from the current time. They give you the body as parsed JSON, not as a typed event.
Verify it yourself
If you’d rather not add a library, the check is short:1
Read the raw body
Use the request body exactly as it arrived, before any JSON parsing. See Use the raw body.
2
Check the timestamp
Reject the request if
webhook-timestamp is more than five minutes from your server’s time. This stops someone replaying an old request.3
Compute the signature
Join
webhook-id, webhook-timestamp and the body with full stops, and compute its HMAC-SHA256 with your decoded secret. Base64-encode the result.4
Compare
Split
webhook-signature on spaces, and take the part after v1, from each. The request is genuine if any of them equals your value. Use a constant-time comparison.Check your code
These values are the Standard Webhooks specification’s own example. Your code should produce this signature from them:
The timestamp is from 2021, so skip the timestamp check while you test with these values. The body has one space after the colon; the signature changes if you remove it.
Use the raw body
The signature covers the exact bytes Cimento sent. If your framework parses the JSON and you turn it back into text, the result can differ from what was signed and the check fails, even though the data is the same. Two things in Cimento’s bodies make this likely:- the body is compact, with no spaces or line breaks;
- the characters
<,>and&inside text are written as\u003c,\u003eand\u0026.
Rotate the secret
Rotate the secret if it may have leaked, or on whatever schedule your policy sets.1
Rotate
On the endpoint’s row, open the ⋯ menu, choose Rotate secret and confirm. Cimento shows Your new signing secret once. Copy it.
2
Update your receiver
Replace the old secret with the new one in your receiver.
webhook-signature holds two signatures: the new secret’s first, then the old one’s. A receiver that accepts a request when any signature matches keeps working throughout, whichever secret it holds. The SDKs, the libraries and the code above do this.
With a Cimento SDK you can also give the receiver both secrets while your deployment moves from the old one to the new one: