Webhook security

​

Signature verification

​

Headers

​

Computing the signature

signed_input = "{t}.{request_body}"
v1           = HEX( HMAC-SHA512( secret, signed_input ) )

​

Verification steps

1. Extract t=<unix-seconds> and v1=<hex> from the x-tesouro-signature header.
2. Look up the shared secret for the key id in x-tesouro-key-id.
3. Construct signed_input = "{t}.{raw_body}".
4. Compute HEX(HMAC-SHA512(secret, signed_input)).
5. Reject with 401 if the computed digest doesn’t match v1.

SECRET="<your shared secret>"
T="<unix-seconds value from x-tesouro-signature>"

EXPECTED=$( { printf '%s.' "$T"; cat request-body.json; } | openssl dgst -sha512 -hmac "$SECRET" -hex | awk '{print toupper($2)}')
echo "$EXPECTED"

​

Replay protection

1. Reject stale requests. Compare t=<unix-seconds> from x-tesouro-signature to the current time and reject anything older than a small window (Tesouro recommends 5 minutes).
2. Deduplicate on deliveryId. Maintain a cache of recently-seen deliveryId values from the envelope and reject any request whose deliveryId you’ve already processed.

​

Secret rotation

• Add the new secret before removing the old one.
• During the rotation period, accept requests signed by either key - use x-tesouro-key-id to select the matching secret per request.
• Remove the old secret only after all in-flight webhooks finish.

​

Endpoint validation

• Register only HTTPS endpoints; plain HTTP isn’t supported.
• Where possible, restrict your webhook handler to known Tesouro source IPs.
• Return 401 for requests that fail validation.

​

Additional options