Skip to main content
Anyone who learns your webhook URL can POST to it. Verify every delivery before you act on it, and reject any request that fails. Trustware signs every delivery to the Standard Webhooks v1.0.0 specification, with the symmetric 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 like whsec_ 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.
Install the library with 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:
  1. Read the webhook-id, webhook-timestamp and webhook-signature headers. Reject the request if any is missing.
  2. Reject the request unless webhook-timestamp is 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.
  3. Build the signed content: webhook-id + . + webhook-timestamp exactly as received + . + the raw body bytes.
  4. Take your secret, remove the whsec_ prefix, and base64-decode the rest. That’s the HMAC key.
  5. Compute HMAC-SHA256 of the signed content with that key.
  6. webhook-signature holds one or more space-separated entries, each v1, followed by a base64 signature. Accept the delivery if any v1 entry 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-signature carries two signatures. Accept the delivery if any one matches.
  • Comparing with ==. Use a constant-time comparison, such as crypto.timingSafeEqual in Node.js or hmac.compare_digest in 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, so webhook-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:
The test vector’s timestamp is in the past, so a verifier that enforces the 5 minute tolerance rejects it. Check the HMAC step on its own, or freeze your test clock at 1793880000.