​
Webhooks

Webhooks allow you to build or set up integrations that subscribe to certain events on Lukittu. When one of those events is triggered, we’ll send an HTTP POST payload to the webhook’s configured URL. Webhooks can be used to react to events that happens on Lukittu real-time.

​
Events

You can create webhooks that subscribe to the various events that occur in your team. You can select which events you want to receive when you create the webhook in webhooks tab on the dashboard. Here are some examples of available events:
  • LICENSE_CREATED
  • LICENSE_UPDATED
  • LICENSE_DELETED
  • CUSTOMER_CREATED
  • PRODUCT_CREATED
  • And many more…

​
Securing your webhooks

Once your server is configured to receive payloads, it will listen for any payload sent to the endpoint you configured. For security reasons, you should limit requests to those coming from Lukittu. To do so, you’ll need to validate the webhook signature. Lukittu uses a HMAC-SHA256 signature to verify the authenticity of the webhook. A secret token is generated for each webhook. On each request, we include the following headers:
  • X-Lukittu-Event: The name of the event that triggered the webhook.
  • X-Lukittu-Timestamp: A UTC timestamp of when the request was sent.
  • X-Lukittu-Signature: The HMAC-SHA256 signature.

​
Verifying signatures

The signature is generated by creating a HMAC with the SHA256 hash function. The secret for the webhook is used as the key, and the message is the concatenation of the timestamp (as a string) and the raw request body, separated by a dot (.). HMAC-SHA256(secret, timestamp + '.' + requestBody) You should always use a constant-time string comparison function to compare the expected signature with the received signature to prevent timing attacks. 
const crypto = require('crypto');

const LUKITTU_SECRET = process.env.LUKITTU_WEBHOOK_SECRET;

function verifySignature(body, headers) {
const timestamp = headers['x-lukittu-timestamp'];
const signature = headers['x-lukittu-signature'];

if (!timestamp || !signature) {
throw new Error('Missing signature headers');
}

const signedPayload = `${timestamp}.${body}`;

const expectedSignature = crypto
.createHmac('sha256', LUKITTU_SECRET)
.update(signedPayload)
.digest('hex');

const trusted = Buffer.from(expectedSignature, 'utf-8');
const untrusted = Buffer.from(signature, 'utf-8');

if (crypto.timingSafeEqual(trusted, untrusted)) {
console.log('Signature is valid!');
return true;
} else {
console.error('Signature is invalid.');
return false;
}
}

​
Delivery and Retries

Lukittu will attempt to deliver a webhook event to your configured URL. If the delivery fails, we will retry sending it.

​
Timeout

A webhook delivery will time out after 5 seconds. Ensure your server can process the request within this timeframe.

​
Retry Mechanism

If your server responds with a non-2xx status code or times out, we will attempt to redeliver the event using an exponential backoff schedule.
  • Maximum Retries: 5 attempts.
  • Retry Schedule: The delay between retries increases exponentially (e.g., 60s, 120s, 240s…).
If a webhook continues to fail, it may be automatically disabled. Specifically, if a webhook has 3 or more consecutive failures within a 48-hour period with no successful deliveries, it will be deactivated to prevent further issues.

​
Discord Webhooks

Lukittu has special support for sending webhooks directly to Discord. If you use a Discord webhook URL, we will automatically format the payload into a Discord-friendly embed format. No signature verification is needed for Discord webhooks.
The image above is just an example of how a Discord webhook might look.