Webhooks

​

Available events

​

Register an endpoint

​

Limits

• Up to 3 active endpoints per organization.
• Up to 5 endpoint creations per hour per organization.
• Test event sends are rate-limited per organization and per endpoint.

​

Payload shape

​

issue.created

{
  "event": "issue.created",
  "id": "ea0c8c0b-4f3d-4b1c-9e7a-d4b1c8e7a4f3",
  "occurredAt": "2026-05-12T08:42:13.512Z",
  "data": {
    "issueId": "9b1c0f8b-a4e2-4ff7-8c5b-7d8a9e2f4c1b",
    "orgId": "00000000-0000-0000-0000-000000000000",
    "title": "Checkout button unresponsive on mobile",
    "description": "Multiple sessions show the checkout button failing to register taps...",
    "status": "unresolved",
    "priority": "high",
    "previewUrl": null,
    "aiVerified": true,
    "sourceType": "session_analysis"
  }
}

​

Headers

​

Verify the signature

Lucent-Signature: t=1715500000,v1=3c35a6b4d9e2f0...

• t — Unix timestamp (seconds) of when Lucent generated the signature.
• v1 — hex-encoded HMAC-SHA256.

1. Read the raw request body. Sign the bytes Lucent sent — re-serializing parsed JSON will not match.
2. Recompute HMAC_SHA256(secret, "${t}.${rawBody}").
3. Compare with v1 in constant time.
4. Reject the request if t is more than 5 minutes from your server clock — this prevents replay of an old, valid request.

import crypto from "node:crypto";

function verifyLucentSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
) {
  // signatureHeader looks like: "t=1715500000,v1=3c35a6b4..."
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => {
      const [k, v] = p.split("=", 2);
      return [k, v ?? ""];
    }),
  );
  const t = parts.t;
  const v1 = parts.v1;
  if (!t || !v1) return false;

  // Reject replays older than 5 minutes.
  const ageSec = Math.floor(Date.now() / 1000) - Number(t);
  if (Number.isNaN(ageSec) || Math.abs(ageSec) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // timingSafeEqual throws if buffers differ in length — guard first.
  const expectedBuf = Buffer.from(expected);
  const v1Buf = Buffer.from(v1);
  if (expectedBuf.length !== v1Buf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, v1Buf);
}

import hmac
import hashlib
import time

def verify_lucent_signature(raw_body: str, signature_header: str, secret: str) -> bool:
    # signature_header looks like: "t=1715500000,v1=3c35a6b4..."
    parts = {}
    for segment in signature_header.split(","):
        if "=" not in segment:
            continue
        k, v = segment.split("=", 1)
        parts[k] = v
    t = parts.get("t")
    v1 = parts.get("v1")
    if not t or not v1:
        return False

    # Reject replays older than 5 minutes.
    try:
        t_int = int(t)
    except ValueError:
        return False
    if abs(int(time.time()) - t_int) > 300:
        return False

    signed = f"{t}.{raw_body}".encode()
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    # compare_digest is naturally length-tolerant.
    return hmac.compare_digest(expected, v1)

​

Retries and idempotency

• Delivery has a 10-second per-request timeout.
• Non-2xx responses, timeouts, and network errors trigger a retry — up to 3 retries with exponential backoff after the initial attempt.
• The same Lucent-Webhook-Id is sent on every attempt. Persist it on success and treat duplicate ids as no-ops.
• Lucent recomputes the signature on each retry, so t (and the Lucent-Signature value) will differ between attempts. The body bytes and Lucent-Webhook-Id stay the same.
• Because the timeout is 10 seconds, your handler should acknowledge fast: validate the signature, enqueue the work, and return 200. Do the actual processing asynchronously.

​

Security model

• HTTPS only. Plain http:// URLs are rejected. URLs with user:pass@ credentials are also rejected — fetch would silently send them as Basic auth.
• Public destinations only. The hostname is resolved fresh on every delivery and its IPs are checked against ipaddr.js ranges. Loopback, private, link-local, and other non-unicast addresses are rejected. This defends against DNS rebinding (an attacker-controlled hostname pointing at 127.0.0.1 between checks).
• Service ports are blocked. Common service ports — SSH (22), SMTP (25), Postgres (5432), MySQL (3306), Redis (6379), Mongo (27017), Elasticsearch (9200/9300), Memcached (11211), Docker (2375/2376), and others — are rejected so webhooks can’t be used to probe internal infrastructure.
• Redirects are not followed. Set the final URL on your endpoint directly.

​

Endpoint management

• last delivery time and HTTP status
• last delivery error label, if any (bad_status:NNN, timeout, tls_error, network_error, url_unsafe)
• a Send test button
• a Revoke button — revoked endpoints stop receiving deliveries immediately and free a slot against the per-org cap.