Every delivery is signed with your endpoint’s signing secret. Verify the signature before you read the body. Anyone can post JSON to your URL; only Payve can sign it.

The scheme

  1. Take t and v1 from the X-Payve-Signature header.
  2. Build the signed string: the timestamp, a full stop, then the raw request body: <t>.<raw body>.
  3. Compute HMAC-SHA256 of that string with your signing secret as the key. Encode it as lowercase hex.
  4. Compare your result with v1 using a constant-time comparison.
  5. Reject the request if t is more than five minutes from your server’s clock.
The secret is the whole string the dashboard gave you, including the whsec_ prefix.
Sign the raw bytes, not parsed JSON. If your framework parses the body and you re-serialise it, key order and spacing change and the signature will not match. Capture the raw body before any JSON middleware runs.

Working examples

Each example verifies the signature, rejects old timestamps, and answers 200 before doing slow work.
The functions that store the event id and queue the work are yours to supply. Handle events safely shows how.

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-Timestamp and the t in 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.
Accept the request if either one verifies against a secret you hold. After 24 hours only X-Payve-Signature is sent.

Common mistakes

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.
A proxy or body-parsing layer may be changing the body. Read the raw bytes as early as you can.
Use a constant-time comparison: crypto.timingSafeEqual, hmac.compare_digest or hash_equals.
Your server clock is wrong, or you are comparing seconds with milliseconds. The timestamp is in seconds.