Integrations
Webhooks
Signed POSTs when a test or flag changes: how to add one, verify it, and what each event carries.
Improve sends a signed POST to your endpoint when a test or flag changes: a test started or paused, a split moved, a flag switched, a change request was asked for or approved, a scheduled change could not run. Send it to Slack, a CI job, your own service. It is per space environment, and developers and admins manage it.
Setting one up
Under Settings → Webhooks, give it:
- a URL: https on a public host. Localhost, private and internal addresses are refused when you save, rather than failing on every delivery.
- the events it wants: all of them, or a selection.
- its signing secret, shown once when you create it, and again only when you rotate it.
Each webhook can be paused (while it is paused nothing is sent for it, and events in that time are not delivered afterwards), sent a test event, and has a log of its deliveries with their response and a redeliver action. Deliveries are pruned after 30 days.
A webhook for production is made in the dashboard, not by an agent: the agent API and MCP list, test and redeliver production's webhooks but refuse to add, change, rotate or delete one there, as an agent must not connect a production endpoint on its own.
The payload
A JSON body:
{
"type": "test.started",
"timestamp": "2026-11-15T09:00:02.114Z",
"space": "space_…",
"environment": "production",
"data": {
"test": {
"id": "test_…",
"slug": "pricing-page",
"name": "Pricing page",
"type": "ab-test",
"state": "active",
"allocation": 50,
"audience": null
},
"changes": ["state"],
"previousState": "draft"
}
}data.test (or data.flag) is the subject as it is after the change. A state event adds previousState and the changes it brought (state, plus settings when those changed with it). A flag's payload carries id, slug, name, state and audience; an options change lists them under changes: ["options"].
Verifying it
Standard Webhooks, so every signature library for it works as it is. Each request has:
| Header | Value |
|---|---|
webhook-id | The delivery's id, the same one on a retry |
webhook-timestamp | Unix seconds when it was sent |
webhook-signature | v1, and the base64 HMAC-SHA256 of {id}.{timestamp}.{body} |
The key is the base64 part of the secret after its whsec_ prefix. Compare in constant time, reject a timestamp that is far from now, and dedupe on webhook-id: delivery is at least once and unordered, so a retry can arrive after a later event.
Events
| Event | When |
|---|---|
test.created | A test was created |
test.updated | Its settings, options or goal events changed, state unchanged (changes: settings, options or goals) |
test.started | It became active |
test.paused | It went from active back to draft |
test.finished | It was finished |
test.archived | It was archived |
test.deleted | It was deleted |
flag.created | A flag was created |
flag.changed | Its state, settings, audience or options changed (changes) |
flag.deleted | It was deleted |
test.review_requested | Someone asked for a change to a test in a reviewed environment |
test.review_closed | That request was approved, sent back or withdrawn |
flag.review_requested | The same, for a flag |
flag.review_closed | The same, for a flag |
test.schedule_failed | A scheduled change or ramp step of a test could not run |
flag.schedule_failed | The same, for a flag |
webhook.test | The test event, from the settings or the agent API |
A save that changes nothing sends nothing. Icons and, on a test, its state-free edits still send test.updated only when a field of that event changed. Audiences have no events: an audience edit changes who a test or flag targets, but the test or flag's own events are where that shows.
The four review events carry the request:
{
"request": {
"id": "change_…",
"subject": { "kind": "test", "id": "test_…", "name": "Pricing page" },
"change": { "kind": "test.state", "state": "active" },
"note": "Ready for Black Friday.",
"status": "applied",
"reason": null,
"requestedBy": "user_…",
"requestedAt": "2026-11-15T08:40:00.000Z",
"decidedBy": "user_…",
"decidedAt": "2026-11-15T08:52:00.000Z",
"applyAt": null,
"scheduledBy": null
}
}schedule_failed carries the same request with its status failed, a reason, its applyAt and, for a ramp, rampStep.
Delivery
- A webhook is written in the same transaction as the change, so an event exists exactly when the change does.
- It is sent right after the change; a failure or an endpoint that answers slowly is retried after 30 seconds, then 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours and 6 hours — about 11 hours in all.
- Any 2xx is a success; a redirect counts as a failure. After the last retry the delivery is
failedin the log, where you can redeliver it. - Delivery is at least once and unordered: dedupe on
webhook-id.
Agent API and MCP
listWebhooks, createWebhook, updateWebhook, deleteWebhook, rotateWebhookSecret, sendTestWebhook, listWebhookDeliveries and redeliverWebhook in the agent API, and the same as MCP tools. The secret comes back once, on creation or rotation.