The scheme
- Take
tandv1from theX-Payve-Signatureheader. - Build the signed string: the timestamp, a full stop, then the raw request body:
<t>.<raw body>. - Compute HMAC-SHA256 of that string with your signing secret as the key. Encode it as lowercase hex.
- Compare your result with
v1using a constant-time comparison. - Reject the request if
tis more than five minutes from your server’s clock.
whsec_ prefix.
Working examples
Each example verifies the signature, rejects old timestamps, and answers200 before doing slow work.
Check your implementation
Use this fixed example to test your code without a live delivery.
Skip the timestamp check when you run this fixed example, because the timestamp is in the past.
Replay protection
A signature proves who sent a request. It does not prove the request is new. Someone who captures a valid delivery could send it to you again. Two checks stop that:- Reject old timestamps.
X-Payve-Timestampand thetin the signature are set fresh on every delivery attempt, including retries. A genuine delivery is always recent. Five minutes of tolerance allows for clock drift. - Reject event ids you have already processed. See Handle events safely.
Keep your server clock synchronised. A clock that is minutes out makes every delivery look too old
or too new.
When a secret is rotated
For 24 hours after a signing secret is rotated, each delivery carries two signatures:X-Payve-Signature, signed with the new secret.X-Payve-Signature-Previous, signed with the old secret.
X-Payve-Signature is sent.
Common mistakes
The signature never matches
The signature never matches
You are almost certainly signing parsed JSON. Sign the raw body. Also check that you are using
the secret for this endpoint and this environment: sandbox and live secrets differ.
It works locally but fails behind a proxy
It works locally but fails behind a proxy
A proxy or body-parsing layer may be changing the body. Read the raw bytes as early as you can.
Comparing with == or ===
Comparing with == or ===
Use a constant-time comparison:
crypto.timingSafeEqual, hmac.compare_digest or
hash_equals.Every delivery is rejected as too old
Every delivery is rejected as too old
Your server clock is wrong, or you are comparing seconds with milliseconds. The timestamp is in
seconds.

