Skip to content

Webhooks

Event types, the payload, signature verification, retries and what happens to a failing endpoint.

Overview#

A webhook is an HTTPS request we send to a URL of yours when something happens in your organization: an experiment starts, a winner is promoted, an AI variant is waiting for review. Use them to post to your team chat, open a task, or keep another system in step without polling the API.

Endpoints are managed by admins under Settings → Webhooks, in the Growth and Agency plans. An organization can register up to 10. Each endpoint can be limited to one site and to the event types it cares about; left unrestricted it receives everything.

Your endpoint#

  • It must be an https:// URL on a public host. Addresses that resolve to private or internal networks are refused, and redirects are not followed.
  • Answer with any 2xx status within 10 seconds. Anything else — another status, a timeout, a connection error — counts as a failed attempt.
  • Acknowledge first, work later. If handling an event takes time, store it and answer immediately.

The settings page has a send test event action that delivers a sample experiment.started event at once and shows your endpoint's answer, and a delivery log with the status and the first 2,000 characters of each response.

The request#

Every event is a POST with a JSON body of the same shape and three headers:

A deliveryhttp
POST /your/endpoint HTTP/1.1
Content-Type: application/json
Lift-Event: experiment.winner_promoted
Lift-Delivery-Id: 0198c1e0-7c2a-7d43-9b1e-2f6a4c8d0e11
Lift-Signature: t=1767225600,v1=5f2b…c9a1

{
  "id": "0198c1e0-7c2a-7d43-9b1e-2f6a4c8d0e11",
  "type": "experiment.winner_promoted",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "organizationId": "0198c1dc-…",
  "siteId": "0198c1dd-…",
  "data": {
    "experiment": { "id": "0198c1de-…", "key": "hero-headline", "name": "Hero headline" },
    "winner": { "id": "0198c1df-…", "name": "Outcome-led headline", "isControl": false },
    "probabilityBest": 0.97,
    "lift": 0.12
  }
}
HeaderValue
Lift-EventThe event type, the same as type in the body.
Lift-Delivery-IdThe id of this delivery, the same as id in the body. It does not change when the delivery is retried.
Lift-SignatureA timestamp and an HMAC of the body, for verification (see below).
FieldValue
idDelivery id.
typeEvent type.
createdAtWhen the event happened, ISO 8601.
organizationIdYour organization.
siteIdThe site the event belongs to, or null for organization-level events.
dataDepends on the event type; see the next section.

Event types#

TypeSent whendata
experiment.startedAn experiment starts.experiment
experiment.pausedA running experiment is paused.experiment
experiment.completedAn experiment ends, with or without a winner.experiment, winner (or null)
experiment.winner_promotedA winner is declared and rolled out, by a person or by autopilot.experiment, winner, probabilityBest, lift
variant.createdA variant is added to an experiment.experiment, variant, source ("human" or "ai")
variant.pending_reviewAn AI-written variant is waiting for approval.experiment, variant
variant.killedA losing variant is stopped.experiment, variant, reason
srm.detectedThe traffic split of an experiment does not match its configured weights.experiment, pValue, reason
usage.limit_reachedThe organization has used up its plan's monthly tracked visitors. Organization-level: siteId is null.limit, used, max, month

In data, experiment is { id, key, name } and variant and winner are { id, name, isControl }. probabilityBest and lift on a promotion are the values at the moment of promotion and can be null when a person promoted a variant before results were computed. To get more than these references, call the REST API with the ids.

New event types and new fields may be added over time. Ignore types you do not handle and fields you do not know.

Verifying signatures#

Anyone who learns your endpoint's URL can post to it. The signature lets you check that a request really came from us and was not altered or replayed. Each endpoint has its own signing secret (lift_whsec_…), shown once when the endpoint is created.

The Lift-Signature header has the form t=<timestamp>,v1=<signature>. To verify it:

  • Take t, a Unix timestamp in seconds, and the request body exactly as received.
  • Compute the HMAC-SHA256 of <t>.<body> — the timestamp, a dot, the raw body — with the signing secret as the key, and encode it as lower-case hex.
  • Compare it with v1 using a constant-time comparison.
  • Reject the request if t is more than 5 minutes away from your clock. That is what stops a captured request from being replayed later.
verify-webhook.js (Node.js)js
import { createHmac, timingSafeEqual } from 'node:crypto';

/**
 * @param secret    the endpoint's signing secret (lift_whsec_…)
 * @param rawBody   the request body exactly as received, before any JSON parsing
 * @param header    the value of the Lift-Signature header
 * @param tolerance maximum age of the signature in seconds
 */
export function verifyWebhook(secret, rawBody, header, tolerance = 300) {
  if (typeof header !== 'string') return false;
  let timestamp = null;
  const candidates = [];
  for (const part of header.split(',')) {
    const eq = part.indexOf('=');
    if (eq <= 0) return false;
    const key = part.slice(0, eq).trim();
    const value = part.slice(eq + 1).trim();
    if (key === 't' && /^\d{1,12}$/.test(value)) timestamp = Number(value);
    if (key === 'v1') candidates.push(value.toLowerCase());
  }
  if (timestamp === null || candidates.length === 0) return false;

  // Replay protection: reject signatures that are too old (or from the future).
  if (Math.abs(Date.now() / 1000 - timestamp) > tolerance) return false;

  const expected = createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody, 'utf8')
    .digest();

  let valid = false;
  for (const candidate of candidates) {
    if (!/^[0-9a-f]{64}$/.test(candidate)) continue;
    if (timingSafeEqual(expected, Buffer.from(candidate, 'hex'))) valid = true;
  }
  return valid;
}

Used in a handler, with deduplication on the delivery id:

Webhook handlerjs
// A route handler (Next.js, or any runtime with the Fetch API on Node).
import { verifyWebhook } from './verify-webhook';

const seen = new Set(); // use a durable store in production

export async function POST(request) {
  const rawBody = await request.text(); // verify the raw text, not re-serialized JSON
  const signature = request.headers.get('Lift-Signature');
  if (!verifyWebhook(process.env.LIFT_WEBHOOK_SECRET, rawBody, signature)) {
    return new Response('invalid signature', { status: 400 });
  }

  // The delivery id is the same on every retry of a delivery: deduplicate on it.
  const deliveryId = request.headers.get('Lift-Delivery-Id');
  if (seen.has(deliveryId)) return new Response(null, { status: 204 });
  seen.add(deliveryId);

  const event = JSON.parse(rawBody);
  switch (event.type) {
    case 'experiment.winner_promoted':
      await notifyTeam(event.data.experiment.name, event.data.winner.name);
      break;
    case 'variant.pending_review':
      await openReviewTask(event.data.experiment.id, event.data.variant.id);
      break;
  }

  // Answer 2xx quickly; do slow work after responding.
  return new Response(null, { status: 204 });
}

The same check in Python:

verify_webhook.pypython
import hashlib
import hmac
import time


def verify_webhook(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    timestamp = None
    candidates = []
    for part in (header or "").split(","):
        key, _, value = part.strip().partition("=")
        if key == "t" and value.isdigit():
            timestamp = int(value)
        elif key == "v1":
            candidates.append(value.lower())
    if timestamp is None or not candidates:
        return False
    if abs(time.time() - timestamp) > tolerance:
        return False

    signed = str(timestamp).encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, candidate) for candidate in candidates)

Verify the raw body

The signature covers the exact bytes we sent. If your framework parses the JSON and you serialize it again, key order and whitespace can differ and the check fails. Read the body as text, verify, and only then parse.

If a secret may have leaked, rotate it in the endpoint's settings. The old secret stops working immediately, so update your receiver at the same moment.

Retries and failures#

Retry schedule
A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours — 6 attempts in total. After the last one it is marked failed and not sent again by itself.
Duplicates
A delivery can reach you more than once, for instance when your answer was lost on the way back. Every attempt of a delivery has the same Lift-Delivery-Id: remember the ids you have processed and skip repeats.
Order
Deliveries are not guaranteed to arrive in the order the events happened. Use createdAt when order matters.
Redelivery
Any past delivery can be sent again from the delivery log. A redelivery is a new delivery with the same payload and a new id.
Failing endpoints are disabled
After 20 deliveries in a row have failed for good, the endpoint is disabled and receives nothing until an admin enables it again. One successful delivery resets the count. Test events never affect it.