Liongard includes the ability to sign all webhook requests, so verification on the receiving end may validate that requests are indeed sent from Liongard and not by any other actor.

📘

Request signing is optional, and does not need to be configured to use Webhooks, nor does configuring it encrypt the data transmitted in any way. If configured, it is simply an additional piece of information passed in a header that may be used to verify the sender is Liongard

Configuring Request Signing

1. After authenticating with our API, make a POST request to v2/webhooks/auth. No request body is necessary.
2. If the API responds successfully, request signing has been configured.

{
    "Success": true,
    "Data": "w5mYaG0RxHaYFP/&a`:xE+ij%UNTpsw{o|Mn^^1UJDuy1"
}

1. The response will include a randomly generated string of characters; this is the signing key. Store this value somewhere safe, because it will only be visible this one time, and it’s needed to perform the signature verification process each time you want to verify that a request received by a webhook was sent from Liongard.

🚧

The signing key may include characters such as \ and ”, which will automatically be escaped when displayed in things like Postman. For example, a signing key that appears in the response in Postman, like below, contains a \ character which has been automatically escaped by Postman as \. When saving the signing key, make sure it is saved in such a way that when you perform the signature verification, you are using the key as "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_ubh\Zsg":

JSON

{
    "Success": true,
    "Data": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_ubh\\Zsg"
}

4. Additional requests made to the v2/webhooks/auth endpoint will return a new signing key that replaces the previously generated one.
5. This signing key is used to sign all webhook requests made for this service provider on Liongard.

Verifying Signed Requests

After configuring request signing, every request sent to the configured URLs (including the test message sent when creating/updating a webhook) will be signed using the signing key. The signature appears in the request as the additional header x-liongard-hmac-sha256.

We’ll use the following as an example of a request the webhook might receive from Liongard:

{
    "method": "POST",
    "url": "https://pretend-this-is-a-real-url.com",
    "headers": [
        // ... other headers
        {
            "name": "x-liongard-hmac-sha256",
            "value": "l4wjYiMnYiuWKj6raqJY4PlMvjvDehGEI1C0FvscQWI="
        },
        {
            "name": "content-type",
            "value": "application/json"
        },
        {
            "name": "accept",
            "value": "application/json, text/plain, */*"
        }
    ],
    "postData": {
        "mimeType": "application/json",
        "text": "{\"message\":\"Test message from Liongard\"}"
    }
}

To verify on the receiving end that a given request was indeed sent from Liongard:

1. Create a base64 HMAC using the sha256 algorithm with the signing key (generated from [here](Configuring Request Signing) ) and the body of the request received (postData).
2. The result of the base64 HMAC key should match the value of the x-liongard-hmac-sha256 header.

If the calculation is performed correctly but the hashes do not match, the request was not signed using the signing key you’re using in your verification. This means either you’re attempting to verify the signature using an old signing key instead of the current one, or that the request was not sent by Liongard.