Skip to Content

Integrations

Webhooks

Signed POSTs when a test or flag changes: how to add one, verify it, and what each event carries.

4 min read

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:

HeaderValue
webhook-idThe delivery's id, the same one on a retry
webhook-timestampUnix seconds when it was sent
webhook-signaturev1, 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

EventWhen
test.createdA test was created
test.updatedIts settings, options or goal events changed, state unchanged (changes: settings, options or goals)
test.startedIt became active
test.pausedIt went from active back to draft
test.finishedIt was finished
test.archivedIt was archived
test.deletedIt was deleted
flag.createdA flag was created
flag.changedIts state, settings, audience or options changed (changes)
flag.deletedIt was deleted
test.review_requestedSomeone asked for a change to a test in a reviewed environment
test.review_closedThat request was approved, sent back or withdrawn
flag.review_requestedThe same, for a flag
flag.review_closedThe same, for a flag
test.schedule_failedA scheduled change or ramp step of a test could not run
flag.schedule_failedThe same, for a flag
webhook.testThe 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 failed in 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.

On this page

Marks in the margin

  • Note
  • Watch out
  • Updated

Scribes marked doubtful lines in the margin. That practice is called obelism.