Check that a webhook really came from WinCloud and was not changed or replayed on the way.
Every webhook request carries an X-RBS-Signature header:X-RBS-Signature: t=1793524445,v1=5f2b0c4e9a7d...e91a
| Part | Meaning |
|---|
t | When the request was signed, in Unix seconds |
v1 | An HMAC-SHA256 signature, in lowercase hex |
v1 is computed over the value of t, a full stop, then the raw request body, using your signing secret as the key. Because t is part of what is signed, nobody can resend an old request with a new time.Check the signature against the raw body bytes, before any JSON parsing. Parsing and re-serialising the JSON changes the bytes, and the check fails even with the right secret.
How to verify a request#
1.
Read the raw request body.
2.
Split the header on , and read the t and v1 values.
3.
Reject the request if t is more than 300 seconds away from your current time.
4.
Compute HMAC-SHA256 over t + . + the raw body, keyed with your signing secret, and write it as lowercase hex.
5.
Compare your value with v1 using a constant-time comparison.
6.
If they match, accept the request. If not, reply 401 and do not process it.
Keep your server clock synchronised (for example with NTP). A clock that drifts more than 300 seconds rejects valid requests.
Code samples#
Each sample returns true only when the signature is valid and recent.
Test your endpoint#
You can check your verification code before any real events arrive by signing a sample body yourself. Run this with your own secret, then send the printed header and body to your endpoint, for example with curl:Send the body exactly as printed, byte for byte, and within 300 seconds of running the script. Your endpoint should accept this request. Change one character of the body or wait more than 300 seconds, and it should reject it with 401.Common problems#
| Symptom | Likely cause |
|---|
| Every request fails the check | The body was parsed before checking, or the wrong secret is in use |
| Requests fail only now and then | Your server clock has drifted, or a proxy is changing the body |
| Valid requests are rejected after a secret change | Your endpoint still holds the old secret |