Verify webhook requests

Learn how to verify webhook requests to ensure they’re coming from CodeQR.

With signature verification, you can determine if the webhook came from CodeQR, and has not been tampered with in transit.

All webhooks are delivered with a CodeQR-Signature header. CodeQR generates this header using a secret key that only you and CodeQR know.

An example header looks like this:

CodeQR-Signature: c9ed6a2abf93f59d761eea69908d8de00f4437b5b6d7cd8b9bf5719cbe61bf46

Finding your webhook’s signing secret

You can find your webhook’s signing secret in the Update Details tab:

Make sure to keep this secret safe by only storing it in a secure environment variable (e.g. CODEQR_WEBHOOK_SECRET). Do not commit it to git or add it in any client-side code.

Verifying a webhook request

To verify, you can use the secret key to generate your own signature for each webhook. If both signatures match then you can be sure that a received event came from CodeQR.

The steps required are:

1. Get the raw body of the request.
2. Extract the signature from the CodeQR-Signature header.
3. Calculate the HMAC of the raw body using the SHA-256 hash function and the secret.
4. Compare the calculated HMAC with the one sent in the CodeQR-Signature header. If they match, the webhook is verified.

Here’s an example of how you can verify a webhook request in different languages:

Next.js

export const POST = async (req: Request) => {
  const webhookSignature = req.headers.get("CodeQR-Signature");
  if (!webhookSignature) {
    return new Response("No signature provided.", { status: 401 });
  }

  // Copy this from the webhook details page
  const secret = process.env.CODEQR_WEBHOOK_SECRET;
  if (!secret) {
    return new Response("No secret provided.", { status: 401 });
  }

  // Make sure to get the raw body from the request
  const rawBody = await req.text();

  const computedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  if (webhookSignature !== computedSignature) {
    return new Response("Invalid signature", { status: 400 });
  }

  // Handle the webhook event
  // ...
};

Why is signature verification important?

Signature verification is a crucial security measure that protects against request forgery and data tampering. Without verification, malicious actors could send fake webhook events to your endpoint, potentially triggering unauthorized actions.

The HMAC-SHA256 signature verification process ensures that only CodeQR can generate valid webhook requests and that payloads haven’t been modified in transit. This provides both authentication (confirming the sender is CodeQR) and integrity (ensuring the message hasn’t been tampered with).