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:
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
}
}| Header | Value |
|---|---|
| Lift-Event | The event type, the same as type in the body. |
| Lift-Delivery-Id | The id of this delivery, the same as id in the body. It does not change when the delivery is retried. |
| Lift-Signature | A timestamp and an HMAC of the body, for verification (see below). |
| Field | Value |
|---|---|
| id | Delivery id. |
| type | Event type. |
| createdAt | When the event happened, ISO 8601. |
| organizationId | Your organization. |
| siteId | The site the event belongs to, or null for organization-level events. |
| data | Depends on the event type; see the next section. |
Event types#
| Type | Sent when | data |
|---|---|---|
| experiment.started | An experiment starts. | experiment |
| experiment.paused | A running experiment is paused. | experiment |
| experiment.completed | An experiment ends, with or without a winner. | experiment, winner (or null) |
| experiment.winner_promoted | A winner is declared and rolled out, by a person or by autopilot. | experiment, winner, probabilityBest, lift |
| variant.created | A variant is added to an experiment. | experiment, variant, source ("human" or "ai") |
| variant.pending_review | An AI-written variant is waiting for approval. | experiment, variant |
| variant.killed | A losing variant is stopped. | experiment, variant, reason |
| srm.detected | The traffic split of an experiment does not match its configured weights. | experiment, pValue, reason |
| usage.limit_reached | The 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
v1using a constant-time comparison. - Reject the request if
tis more than 5 minutes away from your clock. That is what stops a captured request from being replayed later.
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:
// 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:
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
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
createdAtwhen 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.