Validate deliveries

Once your server is configured to receive payloads, it will listen for any delivery that's sent to the endpoint you configured. To ensure that your server only processes webhook deliveries that were sent by CarbonRegistry and to ensure that the delivery was not tampered with, you should validate the webhook signature before processing the delivery further. This will help you avoid spending server time to process deliveries that are not from CarbonRegistry and will help avoid man-in-the-middle attacks.

To do this, you need to:

1. Create a secret token for a webhook.

2. Store the token securely on your server.

3. Validate incoming webhook payloads against the token, to verify that they are coming from CarbonRegistry and were not tampered with.

Create a webhook secret

Go to the "General" tab of your CarbonRegistry app's dashboard.

There you'll be able to define a webhook secret that CarbonRegistry will use to sign webhook POST requests.

Validating webhook deliveries

CarbonRegistry will use your secret token to create a hash signature that's sent to you with each payload. The hash signature will appear in each delivery as the value of the x-icr-signature-256 header. For more information, see "Webhook events and payloads."

In your code that handles webhook deliveries, you should calculate a hash using your secret token. Then, compare the hash that CarbonRegistry sent with the expected hash that you calculated, and ensure that they match.

There are a few important things to keep in mind when validating webhook payloads:

• CarbonRegistry uses an HMAC hex digest to compute the hash.

• The hash signature always starts with sha256=.

• The hash signature is generated using your webhook's secret token and a base64 encoding of the payload contents, stored in the signedData key in the root of the request payload body.

• If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8. Webhook payloads can contain unicode characters.

• Never use a plain == operator. Instead consider using a method like secure_compare or crypto.timingSafeEqual, which performs a "constant time" string comparison to help mitigate certain timing attacks against regular equality operators, or regular loops in JIT-optimized languages.

Testing webhook validation

You can use the following secret and payload values to verify that your implementation is correct:

• secret: "turtleSecret"

• payload: "It's no secret turtles rock."

If your implementation is correct, the signatures that you generate should match the following signature value:

• x-icr-signature-256: sha256=622744da2f7b232aec4663a66d7604bd4f867330487c706b58dbac45af3bb104

Typescript example

require("dotenv").config();
import express, { Request, Response } from "express";
import * as crypto from "crypto";

const app = express();
app.use(express.json());
app.post("/webhook", (req: Request, res: Response) => {
  const signature = req.header("x-icr-signature-256");
  const signedData = req.body.signedData;
  const verified = verify_signature(signature ?? "", signedData ?? "");

  if (!verified) return res.status(403).send("Forbidden");
  res.status(202).send("Accepted");

  console.log("SIGNATURE:", signature);
  console.log("EVENT:", req.body.event);
  console.log("Installation:", req.body.installation);
  console.log("Organization:", req.body.installation.organization);
  console.log("Sender:", req.body.sender);

  const signedDataDecoded = Buffer.from(signedData ?? "", "base64").toString();
  const signedPayload = JSON.parse(signedDataDecoded);
  console.log("Signed Payload:", signedPayload);
});

const verify_signature = (signature: string, signedData: string) => {
  const signatureCheck = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET ?? "")
    .update(signedData)
    .digest("hex");
  const trusted = Buffer.from(`sha256=${signatureCheck}`, "ascii");
  const untrusted = Buffer.from(signature, "ascii");
  try {
    return crypto.timingSafeEqual(trusted, untrusted);
  } catch (error) {
    return false;
  }
};

app.listen(4040, () => {
  console.log("Server is listening on port 4040");
});

For repository see here.

Signed payload

If, for security reasons, you only want to use data that has been signed with your defined secret key you can instead of using the payload body decode the signed data like this:

  const signedDataDecoded = Buffer.from(signedData ?? "", "base64").toString();
  const signedPayload = JSON.parse(signedDataDecoded);
  console.log("Signed Payload:", signedPayload);

The signedPayload will match the request body exactly (except perhaps for the ordering of the keys)