Overview

Webhook security is accomplished via a shared HMAC key. Greenshades will sign each webhook event using HMAC-SHA256 and the key you provide. The key can be anything, but we recommend using a strong password of your choosing. This signature will be included in the webhook request as a header.

Verifying Webhook Signatures

In order to verify the integrity of the webhook event received, you may generate a hash using the request body and the timestamp provided signed with the shared HMAC key. If it matches the Signature in the header, it means that is safe to consume.

Generating HMAC hash

To generate the HMAC hash, use the contatenation result of [timestamp]\n[request body]. e.g.

Headers

The following headers are sent in the event request:

• X-GS-TIMESTAMP
  The timestamp used for the hash
• X-GS-SIGNATURE
  The hash generated by Greenshades

Example

var timestamp = Request.Headers["X-GS-TIMESTAMP"].First().ToString();
var body = RequestBody; // Get from the raw value from the Request;
var content = $"{timestamp}\n{body}";

var signature = GenerateHmacSignature(content);

var isSafe = signature == Request.Headers["X-GS-SIGNATURE"].First().ToString();

For more information about generating the HMAC string, check the recipe below.