Webhook Signature Validation

For security reasons, it is crucial to validate incoming webhook requests to confirm that they originated from PLTcloud. In this article, we will walk you through the process of validating PLTcloud webhook requests using the X-Hub-Signature-256 header.

The X-Hub-Signature-256 header contains a SHA-256 HMAC hex digest of the webhook payload, using the webhook’s authentication token as the key and prefixed with sha256=. The way you verify this signature varies, depending on the language of your code base.

Prerequisites

To follow this guide, you should have:

  • A PLTcloud account and a project that you want to enable webhooks.

  • A web server or application to receive webhook requests.

  • Basic understanding of webhooks, HTTP requests, and cryptographic hashes.

Step 1: Set up the Webhook and Secret token

The first step is to set up a webhook token in your PLTcloud projects’s webhook settings. The webhook will include a token that will be used to create a hash signature that you can compare with the signature sent by PLTcloud in the webhook request.

  • Navigate to your PLTcloud project’s settings.

  • Select Webhook for Serial Number allocation

  • Click on Webhooks settings.

  • Enter the URL for your webook

  • In the Token field, enter a strong, unique token. For PLTcloud, this token must be a hexadecimal string. Remember to store this token securely, as you will need it later for validating the webhook requests.

Step 2: Parse the incoming request

When your application receives a webhook request from PLTcloud, you will need to parse the request’s headers and payload to extract the necessary information for validation.

Read the X-Hub-Signature-256 header from the incoming request. This header contains the hash signature generated by PLTcloud using the secret token and the request payload. Extract the request payload (in JSON format) from the incoming request. This payload contains the data related to the event that triggered the webhook.

Step 3: Compute the HMAC hash

To validate the webhook request, you will need to compute an HMAC hash of the payload using the secret token. This hash will be compared with the X-Hub-Signature-256 signature sent by PLTcloud to confirm the request’s authenticity.

Import a cryptographic library in your application that supports HMAC hashing and the SHA-256 algorithm.

Use the secret token and the request payload to compute the HMAC hash with the SHA-256 algorithm.

For example, in JavaScript:

const crypto = require("crypto");

exports.handler = async (event) => {
  const secretHex = "AC1DBEEF";
  // const secretHex = process.env.WEBHOOK_SECRET_HEX; // Use for production
  const secret = Buffer.from(secretHex, "hex");

  const signature = event.headers["X-Hub-Signature-256"];
  const body = event.body;
  const computedSignature = `sha256=${crypto
    .createHmac("sha256", secret)
    .update(body, "utf8")
    .digest("hex")}`;

  if (
    crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(computedSignature),
    )
  ) {
    return {
      statusCode: 200,
      body: JSON.stringify({
        serial_number: "SN202",
        extra: { MYCUSTOMKEY: "my custom value" },
      }),
    };
  } else {
    return {
      statusCode: 401,
      body: JSON.stringify({ message: "Invalid signature" }),
    };
  }
};

In Go, you could use the hmac and sha256 modules:

func Verify(h *http.Request, token string) error {
    // Extract signature from header
    sigHeader := r.Header["X-Hub-Signature-256"]
    if len(sigHeader) != 1 || len(sigHeader[0]) != 45 {
      return errors.New("invalid signature")
    }

    signature, err := hex.DecodeString(sigHeader[0][7:])
    if err != nil {
      return errors.New("unable to decode signature")
      return
    }

    // Compute Signature
    key, err := hex.DecodeString(token)
    if err != nil {
      return errors.New("unable to decode token")
    }

    mac := hmac.New(sha256.New, key)

    body, err := ioutil.ReadAll(r.Body)
    if err != nil {
      return errors.New("unable to read body")
    }

    mac.Write(body)
    computed := mac.Sum(nil)

    // Compare Signature
    if !hmac.Equal(signature, computed) {
      return errors.New("signature mismatch")
    }
  }

References

See also