Verify Webhook Requests

Every webhook delivery is signed with an HMAC-SHA256 signature so you can verify that requests originate from Tracore and have not been tampered with.

How it works

1. When you create a webhook, Tracore generates a signing secret and returns it in the response.
2. Each delivery includes a x-tracore-signature header containing the HMAC-SHA256 signature of the request body.
3. Your server computes the expected signature using the shared secret and compares it to the header value.

Verification example

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  const expectedBuffer = Buffer.from(expected, "hex");
  const signatureBuffer = Buffer.from(signature, "hex");

  if (expectedBuffer.length !== signatureBuffer.length) {
    return false;
  }

  return timingSafeEqual(expectedBuffer, signatureBuffer);
}

Usage in an Express handler

import express from "express";

const app = express();

app.post("/webhooks/tracore", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-tracore-signature"] as string;
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(payload);
  console.log("Received event:", event.event);

  // Handle the event
  switch (event.event) {
    case "run.completed":
      // Process extracted data
      break;
    case "run.failed":
      // Handle failure
      break;
  }

  res.status(200).send("OK");
});

Best practices

• Always verify signatures. Never process webhook payloads without checking the signature first.
• Use timingSafeEqual. A constant-time comparison prevents timing attacks against the signature check.
• Store secrets securely. Keep your webhook signing secret in environment variables, not in source code.
• Return 200 quickly. Acknowledge the webhook with a 200 response before doing heavy processing. Use a queue if your handler takes more than a few seconds.