v1 (HMAC-SHA256) scheme. The simplest correct approach is the official Standard Webhooks library for your language. It checks the signature for you, in constant time, and rejects a webhook-timestamp more than 5 minutes away from your clock.
Your signing secret
Your secret looks likewhsec_ followed by base64. The Client Dashboard shows it once, when you register your webhook URL or rotate the secret. Store it the way you store other server secrets, such as in an environment variable or a secrets manager, and never ship it to a browser.
If you lose it, rotate it from the dashboard. Trustware can’t show an existing secret again. See rotate the secret.
Verify with a library
The Standard Webhooks libraries accept the secret exactly as the dashboard shows it,whsec_ prefix included.
npm install standardwebhooks or pip install standardwebhooks. Libraries for other languages are listed on the Standard Webhooks site.
Verify without a library
If you can’t add a dependency, the scheme is short enough to implement directly:- Read the
webhook-id,webhook-timestampandwebhook-signatureheaders. Reject the request if any is missing. - Reject the request unless
webhook-timestampis whole Unix seconds, digits only, within 5 minutes of your clock, the tolerance the Standard Webhooks libraries use. This stops an old, captured delivery from being replayed. - Build the signed content:
webhook-id+.+webhook-timestampexactly as received +.+ the raw body bytes. - Take your secret, remove the
whsec_prefix, and base64-decode the rest. That’s the HMAC key. - Compute HMAC-SHA256 of the signed content with that key.
webhook-signatureholds one or more space-separated entries, eachv1,followed by a base64 signature. Accept the delivery if anyv1entry matches your HMAC. Compare in constant time, and ignore entries with any other version prefix.
Node.js
Common mistakes
- Verifying a parsed body. Frameworks that parse JSON before your handler runs hand you an object, not the bytes Trustware signed. Re-serializing it changes whitespace or key order, and the signature fails. Configure the route to give you the raw body.
- Using the secret with its prefix as the key. The HMAC key is the base64-decoded part after
whsec_, not the string itself. The libraries handle this for you. - Checking only the first signature. During a secret rotation,
webhook-signaturecarries two signatures. Accept the delivery if any one matches. - Comparing with
==. Use a constant-time comparison, such ascrypto.timingSafeEqualin Node.js orhmac.compare_digestin Python. - A drifting server clock. The timestamp check fails every delivery if your clock is more than 5 minutes off. Keep it synced with NTP.
Secret rotation
When you rotate your secret, Trustware signs every delivery with both the old and the new secret for 24 hours, sowebhook-signature holds two v1 entries. Deploy the new secret to your server within that window. A delivery verifies against either secret, so you don’t drop any during the switch.
After 24 hours the old secret is deleted and deliveries carry only the new signature. Rotating again inside the 24 hours ends the previous secret’s overlap at once, so a delivery never carries more than two signatures.
Test vector
Use this to check your own implementation. The body is exactly the bytes shown: 286 bytes, with no trailing newline.
During a rotation to a second secret,
whsec_ICEiIyQlJicoKSorLC0uLzAxMjM0NTY3ODk6Ozw9Pj8= (key bytes 0x20 to 0x3f), the same delivery carries the new secret’s signature first:
1793880000.