{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/hpp_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Signature in HPP Webhooks","description":"The specifications of Ratepay's APIs for easy payment transactions.","siteUrl":"https://docs.ratepay.com","keywords":"Ratepay developer portal, Ratepay api portal, Ratepay api reference docs","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"signature-in-hpp-webhooks","__idx":0},"children":["Signature in HPP Webhooks"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"badges-container"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"reading-time-badge"},"children":["⏱ 2 min"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"author-badge"},"children":["👤 Onboarding Developer Team (Alexandre S.)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a measure to verify whether a webhook call really comes from HPP, you can use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Signature"]}," header that is sent alongside the requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The header is based on the following algorithm:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"signed_payload = timestamp + \".\" + raw_body\nsignature = HMAC_SHA256(secret, signed_payload)\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The current timestamp is combined with the request body"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Then, a hash is calculated using the HMAC-SHA256 algorithm"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The header itself contains the following:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"t=TIMESTAMP_AS_NUMBERS,v1=BASE64_SIGNATURE\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, considering the timestamp ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1778083162"]}," (equivalent to Wednesday, May 6, 2026, at 3:59:22 PM UTC), the payload ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"key\": \"value\"}"]},", and the secret key ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["my secret"]},", the header value would be:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"X-Signature:\"t=1778083162,v1=Rp1SRtrZLCubfGIGIXXPBS0UnOHnvcDbDbDtWC4nWvQ=\"\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's break it down:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The timestamp used in the signature is generated by Ratepay and included in the header, identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The algorithm uses this timestamp together with the payload ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"key\": \"value\"}"]}," as input."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The output of the algorithm is encoded using Base64."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The resulting signature is included in the header, identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By reproducing these steps upon receiving a message (and using the same secret), you can verify that the request originated from Ratepay."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"final-note-on-security","__idx":1},"children":["Final note on security"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},"headings":[{"value":"Signature in HPP Webhooks","id":"signature-in-hpp-webhooks","depth":1},{"value":"Final note on security","id":"final-note-on-security","depth":2}],"frontmatter":{"seo":{"title":"Signature in HPP Webhooks"},"disableImagesOptimization":true,"markdown":{"toc":{"hide":false,"depth":3}}},"lastModified":"2026-05-06T15:37:33.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/hosted_payment_page/webhooks_signature","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}