This guide explains how to use HMAC-SHA256 with a pre-shared secret to verify API request authenticity
What is HMAC?
HMAC (Hash-based Message Authentication Code) uses a cryptographic hash function (SHA256 in our case) and a pre-shared secret to generate a signature. This signature ensures the integrity and authenticity of the message payload.
How the HMAC Signature is Generated
We hash the request payload using the SHA256 algorithm to generate a hex-encoded HMAC signature. This signature is included in the request header, as shown below:
You can then use a pre-shared secret as the key to verify that the request originated from us and that the payload was not altered."
x-server-authorization-hmac-sha256:
65060aeeee*********************eeebdad3196e9d7
Make sure to capture the complete raw JSON body exactly as received, with no formatting, whitespace, or encoding transformations.
Obtaining HMAC Secret Key
One HMAC secret key will be provided per environment;
Staging (Testing Environment)
Prior to being certified, we sign requests using a temporary secret value, which may be either:
channelLink(present in most calls to partner endpoints)locationId(applicable to Dispatch API integrations and Get Products webhook for POS integrations)
Production (Live Environment)
Certified partners can generate their production HMAC secret via the Integration settings. Refer to this guide for step-by-step instructions.
For a deeper understanding of HMAC see this article on Wikipedia.
When calculating the HMAC for GET requests (which typically have no body), use an empty string as the payload.