"Webhook overview" documentation

[TomVG]

I've recently had to setup the Webhook for an application and found it hard to validate the signature in the header. First of all, it does not clearly specify that we need to use the OAuth 2.0 in order to get the X-Loyverse-Signature header in the HTTP request. Secondly, the steps to validate the header seem to be incorrect according to the documentation and what I heard from support.

Lets go into details:

In order to get the X-Loyverse-Signature header in the HTTP request, you will have to follow the Authorization documentation for the OAuth 2.0 option (https://developer.loyverse.com/docs/#section/Authorization/OAuth-2.0). After getting your access token, you then use this token one time on Postman to create a Webhook (https://developer.loyverse.com/docs/#tag/Webhooks/paths/~1webhooks~1/post). In my case, I did all these steps on postman on my local machine (because you need to sign in with a browser) and then pointed the webhook to my application URL in production, while also logging the headers and body of those requests. Now, all your webhooks are comming with the header for you to validate.

How to validate the X-Loyverse-Signature header in the HTTP request? According to the docs, it talks about base64-encoded headers, but this is not the case. It also does not specify which algorithm it uses to encode, so this makes it harder to validate. The messages that come through the webhook are encoded encoded with HmacSHA1 and are not encoded in base64. What I did in a JAVA application was (sorry I could not copy and paste because of formatting issues):

 

With this post I was hoping Loyverse could update the documentation so that the next developers trying to setup this webhook have a better experience doing so.

I really enjoy all of Loyverse products, and I'm trying to contribute to it by helping with this if needed. My suggestion on the documentation part would be:

SECTION VALIDATE NOTIFICATIONS (https://developer.loyverse.com/docs/#section/Webhooks-overview/Validate-notifications)
"To validate webhook requests from Loyverse, you need to ensure they are genuine and secure. First, set up your webhooks using the OAuth 2.0 process to receive the X-Loyverse-Signature header in incoming requests. Use your access token to create the webhook through the API, as detailed in the Authorization Documentation. Without this setup, the signature header required for validation won't be included in the webhook requests.

The X-Loyverse-Signature header is generated using the HmacSHA1 algorithm with your application's secret key and the request payload (raw body). To validate the request, compute the HMAC for the payload using your secret key and compare it to the signature header. If they match, the request is authentic. This ensures secure communication and protects your webhook endpoint from unauthorized access."