How the signature works
TheX-Qwairy-Signature header is sha256= followed by the hexadecimal HMAC-SHA256,
keyed with your signing secret, of this string:
- Use the raw bytes of the body, before any JSON parsing. A parsed and re-serialized body produces a different signature.
X-Qwairy-Timestampis the Unix time in seconds when this attempt was signed. Each retry is signed again with a new timestamp.- Compare in constant time.
- Reject requests whose timestamp is more than 5 minutes from your clock. This limits replays of a captured request.
Check your code with a test vector
This synthetic example lets you confirm your implementation. It uses the secretsynthetic-signing-secret and the timestamp 1793610000.
Node.js
Python
Rotate the secret
After Rotate the signing secret, theX-Qwairy-Signature header carries two values separated by a comma for 24 hours.
The first is signed with the new secret and the second with the previous secret:
- Rotate the secret and store the new value.
- Deploy the new secret to your receiver. Requests keep passing during the overlap, whichever secret you hold.
- After 24 hours, requests carry a single signature again.
previousSecretExpiresAt in the endpoint gives
the end of the overlap.
Troubleshooting
- Every request fails. Check that you sign the raw body and not a re-serialized one, and that no middleware changes it before your handler.
- Only some requests fail. Check your server clock against the 5-minute tolerance.
- A request fails after a rotation. Confirm that you use the new secret, and that you compare every value of the header.

