Skip to main content
Verify every integration webhook request before you trust it. Qwairy signs each attempt with the secret of the endpoint, so a valid signature shows that the request came from Qwairy and that the body was not changed. Do not rely on a token embedded in the endpoint URL instead. Every key of the team that can read its webhooks, read-only keys included, receives the full URL.

How the signature works

The X-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-Timestamp is 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 secret synthetic-signing-secret and the timestamp 1793610000.
The timestamp tolerance rejects this example on a real clock, so pass a fixed “now” in your test.

Node.js

Use it with a raw body parser, for example in Express:

Python

Use it with the raw body, for example in Flask:

Rotate the secret

After Rotate the signing secret, the X-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:
Both examples above split the header and accept the request when any value matches the secret you hold. To rotate without losing events:
  1. Rotate the secret and store the new value.
  2. Deploy the new secret to your receiver. Requests keep passing during the overlap, whichever secret you hold.
  3. 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.