When you add an outbound webhook endpoint, Lumant generates a signing secret for that endpoint.
This secret is used to sign each webhook request, so your application can verify that the request came from Lumant and that the payload was not changed before it reached your server.
In this guide, we'll show you how to authenticate outbound webhooks using the X Lumant Signature header.
Copy your signing secret
When you create a webhook endpoint, Lumant shows you a signing secret.
Copy this secret immediately and store it securely.
The signing secret is only shown once.
Example:
lmsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Do not share this secret publicly or include it in frontend code.
How webhook signatures work
Lumant signs each webhook request using your endpoint signing secret.
The signature is sent in the X Lumant Signature header.
The header value uses this format:
sha256={signature}The sha256= prefix tells your application which signing algorithm was used.
Your application should use the raw request body and your signing secret to calculate the expected signature. If the expected signature matches the signature from the header, the webhook can be trusted.
Verify the signature
To verify a webhook request, your server should:
Read the raw request body.
Get the X Lumant Signature header.
Remove the
sha256=prefix.Create an HMAC SHA256 signature using your signing secret.
Compare the received signature with the expected signature.
Use a timing safe comparison when checking the signatures.
AI implementation prompt
Integrate Lumant outbound webhooks into this project using the existing framework and coding style.
Create a secure webhook endpoint that:
1. Accepts POST requests.
2. Reads the raw request body.
3. Verifies the `X-Lumant-Signature` header using the provided Lumant signing secret.
4. Uses HMAC SHA256 to generate the expected signature.
5. Expects the header format `sha256={signature}`.
6. Uses a timing safe comparison to verify the signature.
7. Rejects invalid requests with HTTP 401.
8. Parses the JSON payload only after the signature has been verified.
9. Returns HTTP 200 after successful processing.
Write complete production ready code with appropriate error handling and comments where necessary.
JavaScript examples
This example shows how to verify a Lumant webhook signature using plain JavaScript with Node.js.
import crypto from "crypto";
export const verifyLumantWebhook = (rawBody: Buffer | string, signatureHeader: string | undefined, signingSecret: string): boolean => {
if (!signatureHeader) {
return false;
}
const prefix = "sha256=";
if (!signatureHeader.startsWith(prefix)) {
return false;
}
const receivedSignature = signatureHeader.slice(prefix.length);
const expectedSignature = crypto
.createHmac("sha256", signingSecret)
.update(rawBody)
.digest("hex");
const receivedBuffer = Buffer.from(receivedSignature, "hex");
const expectedBuffer = Buffer.from(expectedSignature, "hex");
if (receivedBuffer.length !== expectedBuffer.length) {
return false;
}
return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
};
Important notes
Always use the raw request body when generating the expected signature.
Store your signing secret securely, for example as an environment variable.
Do not expose the signing secret in frontend code, public repositories, logs, or client side applications.
Use a timing safe comparison instead of comparing signatures with ===.
If you lose the signing secret, create a new webhook endpoint or rotate the secret if this option is available.