Skip to main content

Security

Authentication for submitted payloads​

Authentication mechanisms are not required for the submitted payloads due to their lightweight content.

You must inspect the callback URL received as part of the notifications at the client endpoint to ensure the access tokens are not leaked when accessing links.

If you require authentication, the notification request will have the Authorization header that signs the payload content. You need to securely provide LetsGetChecked a strong secret key (signing key) in base64 format.

When notifications are signed, the POST requests include the following details:

  • In the authorization header, a type (scheme) value of LGC2-HMAC-SHA256
  • The credentials value of HMAC_SHA256 (signing key, request body). HMAC_SHA256 should be readily available in most modern stacks.
    Tip: LetsGetChecked uses the client’s secure HMAC (Hash-based message authentication code) key for authentication to ensure malicious attackers cannot directly access the service to obtain PHI. It is a more secure method of managing webhooks. For more information about the HMAC_SHA256 definition, see HMAC: Keyed-Hashing for Message Authentication.

Example​

The following example request displays the format of the authorization header and credentials value.

You can use this example on your side to test your implementation. You need to stringify the body and provide it along with the signing key into the HMAC SHA256 algorithm. You then take the result and convert it to a Base64 string and compare both. They should match.

Authorization: LGC2-HMAC-SHA256 39enefrHVb+3OPH18TdAxTcVflmjLk0ymDmhx8v79j0=

Request body​
{
   "lgcOrderRef":"d5364386-957f-41e1-8e75-282f7588133d",
   "callbackURL":"{LGC-API}/123/order/123123123"
}
Signing key​

KTNNPy4qyZuayiJuGUGetQGya46nTTb6ZRSmPNhU3y9R3u2cZY4whGsDOaKtgJmmQ5/aIzAVJNxorX2EjFD6kg==