Skip to main content
Anyone who learns your endpoint’s URL can send it a request. Cimento signs every request with your endpoint’s signing secret, so you can tell its requests from anyone else’s. Verify the signature before you trust a request. Cimento publishes SDKs for Go and TypeScript that verify a request and hand you the event. Cimento also follows the Standard Webhooks specification, so in any other language you can verify with one of its open-source libraries instead of writing the check yourself.

Verify with a Cimento SDK

Install the SDK. Neither has any dependencies.
Then give it your endpoint’s signing secret, the whsec_... value Cimento shows once when you create the endpoint.
The SDK does the whole check for you:
  • it verifies the signature over the body exactly as it arrived;
  • it rejects a request whose webhook-timestamp is 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 data typed for the event’s type. See Reading events with an SDK.
In Go, 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
Each SDK’s reference has the rest: the errors a failed check gives, and how to sign a request of your own to test your receiver.

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
The key is your signing secret with the 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
The libraries also reject a request whose 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, \u003e and \u0026.
So read the body as bytes, verify, and only then parse it.

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.
For 24 hours after a rotation, Cimento signs each request with both secrets, so 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:
After 24 hours, only the new secret is used.
If you rotate again within those 24 hours, the oldest secret stops working at once. Cimento keeps one previous secret, not two.