Webhooks

Setup

Create a webhook endpoint from Settings → Developers → Webhooks, providing the destination URL (must use HTTPS) and the events you want to subscribe to. Creating it generates a signing secret that's only shown once.

Headers on every delivery

Verifying the signature

The signature is an HMAC-SHA256 computed over the string {timestamp}.{raw body}, using your webhook secret as the key. Recompute it and compare against X-Lueira-Webhook-Signature before processing the event; reject any delivery whose timestamp is older than 5 minutes to guard against replay attacks.

const crypto = require("crypto");

function isValidSignature(secret, timestamp, rawBody, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return signatureHeader === `sha256=${expected}`;
}

Retries and endpoint health

If your endpoint doesn't respond with a 2xx status, the delivery is retried up to 6 times with exponential backoff (roughly 1 min, 5 min, 30 min, 2 h, 6 h, 12 h). After 20 consecutive failures the endpoint is automatically disabled and you'll get an email notice; you can re-enable it, redeliver individual events, or send a test event from the panel.

Event catalogue