# Webhooks (/docs/integrations/webhooks)

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](/docs/terminology#space) [environment](/docs/guides/environments), and developers and admins manage it.

## Setting one up [#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](/docs/api/agents) 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 [#the-payload]

A JSON body:

```json
{
	"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 [#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 [#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](/docs/guides/approvals) |
| `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](/docs/guides/scheduled-changes) 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:

```json
{
	"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 [#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 [#agent-api-and-mcp]

`listWebhooks`, `createWebhook`, `updateWebhook`, `deleteWebhook`, `rotateWebhookSecret`, `sendTestWebhook`, `listWebhookDeliveries` and `redeliverWebhook` in the [agent API](/docs/api/agents), and the same as MCP tools. The secret comes back once, on creation or rotation.
