As a measure to verify whether a webhook call really comes from HPP, you can use the X-Signature header that is sent alongside the requests.
The header is based on the following algorithm:
signed_payload = timestamp + "." + raw_body
signature = HMAC_SHA256(secret, signed_payload)This means:
- The current timestamp is combined with the request body
- Then, a hash is calculated using the HMAC-SHA256 algorithm
The header itself contains the following:
t=TIMESTAMP_AS_NUMBERS,v1=BASE64_SIGNATUREFor example, considering the timestamp 1778083162 (equivalent to Wednesday, May 6, 2026, at 3:59:22 PM UTC), the payload {"key": "value"}, and the secret key my secret, the header value would be:
X-Signature:"t=1778083162,v1=Rp1SRtrZLCubfGIGIXXPBS0UnOHnvcDbDbDtWC4nWvQ="Let's break it down:
- The timestamp used in the signature is generated by Ratepay and included in the header, identified by
t. - The algorithm uses this timestamp together with the payload
{"key": "value"}as input. - Using the shared secret key (known to both Ratepay and you, but exchanged via separate channels), the data is processed using the HMAC-SHA256 algorithm.
- The output of the algorithm is encoded using Base64.
- The resulting signature is included in the header, identified by
v1.
By reproducing these steps upon receiving a message (and using the same secret), you can verify that the request originated from Ratepay.
Note that this mechanism ensures the authenticity of the request, not its encryption. Make sure your webhook is only accessible via HTTPS to ensure that the request is encrypted.