Request Verification

Webhook Requests Signature Verification

To ensure the integrity and authenticity of webhook requests sent from our system, we include a signature in each request. This allows you to verify that the request originated from us and that the payload has not been tampered with.

This process is similar to how GitHub secures its webhook deliveries.

Signature Header

Each webhook request will include an X-Lucra-Signature HTTP header. This header contains a hexadecimal HMAC (Hash-based Message Authentication Code) signature of the request payload.

Get Your Webhook Record Secret

Once a webhook is registered with your server URL, use the webhook id to request the shared secret from your Lucra representative. This will be shared through a secure method like, for example, single share secret links.

Generating the Signature (Our Side)

When an event triggers a webhook call to your configured URL, our system generates the signature for the X-Lucra-Signature header. This is done by calculating an HMAC (e.g., HMAC-SHA256) of the raw JSON request body using the unique shared-secret associated with your specific webhook configuration. The resulting hexadecimal digest is then formatted and sent as the header value.

Verifying the Signature (Your Side)

To verify the signature on your end, you need to perform a similar calculation and compare the result with the signature we sent.

Steps to Verify:

• Extract the Signature: Get the value of the X-Lucra-Signature header from the incoming request.

• Prepare the Payload: Use the raw request body. It's crucial to use the exact same byte sequence that we used to generate the signature. Do not parse and then re-stringify the JSON, as this might alter its structure (e.g., whitespace, key order) and result in a mismatched signature.

• Retrieve Your Shared Secret: Obtain the shared-secret that is created upon webhook registration from your Lucra representative.

• Calculate the Expected Signature: Compute the HMAC of the raw request body using the identified algorithm and your shared-secret.

• Compare Signatures: Compare the signature extracted from the X-Lucra-Signature header with the expected signature you just calculated. They must be an exact match. To prevent timing attacks, use a constant-time string comparison function.

Important Considerations:

• Transactional Events: For events that are considered as transactional, this verification is crucial as these events can only be configured for a single endpoint. A successful verification ensures that critical transactional data is processed securely and correctly.

• Shared Secret Management: Keep your shared-secret confidential. Treat it like a password. If a secret is compromised, you should generate a new configuration record and delete the compromised one, get in contact with your Lucra representative to get your new secret and update your verification logic accordingly.

• Raw Body: Always use the raw request body for signature calculation. Many web frameworks provide access to the raw body before any parsing occurs.

Examples

Let's assume the hashing algorithm is HMAC-SHA256 and the header format is sha256=.

Example Shared Secret: yourSecretToken123

Example Request Body (raw JSON):

{
  "event_type": "item.created",
  "payload": {
    "id": "item_abc123",
    "name": "New Item",
    "quantity": 10
  },
  "timestamp": "2025-05-29T12:00:00Z"
}

Signature Verification:

This example uses Node.js and its built-in crypto module.

import * as crypto from 'crypto';
import { Buffer } from 'buffer'; // Important for raw body handling

// Example incoming request data (simulated)
const receivedSignatureHeader = 'sha256=f721a137980b935991d300a9e9f5375a5171726c8e98af11e1f18a321ab45678'; // From X-Lucra-Signature
const rawRequestBody = Buffer.from('{"event_type":"item.created","payload":{"id":"item_abc123","name":"New Item","quantity":10},"timestamp":"2025-05-29T12:00:00Z"}', 'utf-8');
const clientSharedSecret = 'yourSecretToken123'; // Your stored shared secret




function verifyWebhookSignature(
  signatureHeader: string,
  rawBody: Buffer,
  secret: string
): boolean {
  if (!signatureHeader) {
    console.error("Signature header is missing.");
    return false;
  }

  const parts = signatureHeader.split('=');
  if (parts.length !== 2 || parts[0] !== 'sha256') {
    console.error("Invalid signature format. Expected 'sha256=<signature>'.");
    return false;
  }
  const receivedSignature = parts[1];

  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody); // Pass the raw Buffer directly
  const expectedSignature = hmac.digest('hex');

  // Use crypto.timingSafeEqual for security
  try {
    // Ensure both buffers have the same byte length for timingSafeEqual
    const receivedSigBuffer = Buffer.from(receivedSignature, 'hex');
    const expectedSigBuffer = Buffer.from(expectedSignature, 'hex');

    if (receivedSigBuffer.length !== expectedSigBuffer.length) {
      console.error("Signature length mismatch.");
      return false;
    }

    return crypto.timingSafeEqual(receivedSigBuffer, expectedSigBuffer);
  } catch (error) {
    console.error("Error during signature comparison:", error);
    return false;
  }
}

// --- How to use it in an Express.js like framework ---
// Make sure to get the raw body *before* any JSON parsing middleware runs.
// For Express, you might use something like:
// app.use(express.json({
//   verify: (req, res, buf, encoding) => {
//     if (buf && buf.length) {
//       (req as any).rawBody = buf; // Store raw body on request
//     }
//   }
// }));
//
// Then in your route handler:
// const signature = req.headers['x-lucra-signature'] as string;
// const rawBody = (req as any).rawBody; // Use the stored raw body

const isValid = verifyWebhookSignature(receivedSignatureHeader, rawRequestBody, clientSharedSecret);

if (isValid) {
  console.log("Webhook signature is valid. Processing event...");
  // Process the webhook payload (JSON.parse(rawRequestBody.toString('utf-8')))
} else {
  console.error("Webhook signature is invalid. Ignoring request.");
  // Respond with an error (e.g., HTTP 401 Unauthorized or 403 Forbidden)
}