# Webhook Events

Improvado can notify your endpoint about 90 event types. This page lists every one of them, with the exact payload you will receive.

See the [platform webhooks guide](https://improvado.io/docs/webhooks) for how to register and verify an endpoint.

## Envelope

Every delivery is an HTTP `POST` with the same outer shape:

```json
{
  "id": "unique event identifier",
  "type": "event type name",
  "timestamp": "when the event occurred",
  "data": "{ ... }"
}
```

| Header | Purpose |
|---|---|
| `X-Improvado-Signature` | HMAC-SHA256 of the raw request body, keyed with your signing secret. Recompute it and compare. |
| `X-Improvado-Idempotency-Key` | Deduplicate retried deliveries |

**Delivery latency:** p50 ~13-15 min, p95 ~20-26 min after the event occurs. Webhooks suit automation and integration workflows, not use cases needing an instant reaction.

**All payload values are strings.** A field shown empty below is empty in production for that event type — it is not an omission.

## Payload shapes

The `data` object is determined by the event's **aggregate class, not by the event type**. That means 12 shapes cover all 90 events — match on the shape, not on each event name.

### Account

Used by 8 events: `account_created`, `account_disabled`, `account_disabled_for_copied_connection`, `account_enabled`, `account_enabled_for_copied_connection`, `account_item_changed`, `account_name_changed`, `enabled_for_embedded_extraction_changed`.

Example (`account_created`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "account_created",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "Account",
    "product_domain_event_class": "AccountCreated",
    "product_domain_event_usecase": "",
    "product_domain_event": "",
    "datasource_account_id": "123456",
    "datasource_remote_account_id": "act-1029384756",
    "datasource_remote_account_name": "My Ad Account",
    "datasource_connection_id": "654321",
    "datasource_connection_title": "My Facebook Connection",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace"
  }
}
```

### Extraction

Used by 14 events: `additional_params_changed`, `custom_filters_changed`, `extraction_account_changed`, `extraction_completed`, `extraction_created`, `extraction_marked_as_deleting`, `extraction_paused`, `extraction_schedules_changed`, `extraction_template_changed`, `extraction_unpaused`, `fields_changed`, `historical_download_started`, `regular_download_started`, `sync_historical_data_changed`.

Example (`extraction_completed`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "extraction_completed",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "Extraction",
    "product_domain_event_class": "ExtractionCompleted",
    "product_domain_event_usecase": "",
    "product_domain_event": "",
    "is_action_log": "1",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace",
    "dts_order_params_id": "123456",
    "order_id": "654321"
  }
}
```

### Agency

Used by 5 events: `agency_created`, `agency_is_test_changed`, `agency_migrated_to_workspace_separated_schemas`, `agency_offboarded`, `agency_toggle`.

Example (`agency_created`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "agency_created",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "Agency",
    "product_domain_event_class": "AgencyCreated",
    "product_domain_event_usecase": "CreateOrUpdateAgencyUsecase",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace"
  }
}
```

### AgencyInvite

Used by 4 events: `agency_invite_created`, `invite_accepted`, `invite_deleted`, `invite_sent`.

Example (`invite_sent`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "invite_sent",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "AgencyInvite",
    "product_domain_event_class": "InviteSent",
    "product_domain_event_usecase": "InviteUserToAgencyUseCase",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace",
    "agency_invite_uuid": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
    "inviter_user_id": "1234",
    "invitee_user_email": "teammate@example.com",
    "invitee_user_type": "New User",
    "invitee_user_first_name": "",
    "invitee_user_last_name": "",
    "agency_invite_requested_at": "2026-04-06 11:39:46.752",
    "agency_invite_accepted_date": null,
    "agency_invite_workspaces_json": "{\"1\":234}"
  }
}
```

### Connection

Used by 9 events: `connection_accounts_update_error`, `connection_accounts_update_fail`, `connection_accounts_update_started`, `connection_accounts_update_success`, `connection_created`, `connection_deleted`, `connection_invalidated`, `connection_privacy_updated`, `connection_reconnected`.

Example (`connection_created`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "connection_created",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "Connection",
    "product_domain_event_class": "ConnectionCreated",
    "product_domain_event_usecase": "",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace",
    "datasource_connection_id": "654321",
    "datasource_name": "facebook",
    "datasource_connection_title": "My Facebook Connection"
  }
}
```

### DestinationConnection

Used by 11 events: `create_load_changed`, `destination_connection_changed`, `destination_connection_check_run`, `destination_connection_created`, `destination_connection_deleted`, `error_text_changed`, `gbq_by_improvado_created`, `gbq_by_improvado_for_sandbox_created`, `secret_key_changed`, `status_changed`, `title_changed`.

Example (`destination_connection_created`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "destination_connection_created",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "DestinationConnection",
    "product_domain_event_class": "DestinationConnectionCreated",
    "product_domain_event_usecase": "CreateOrUpdateOAuthDestinationConnection",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace",
    "destination_connection_id": "11112222-3333-4444-5555-666677778888",
    "destination_connection_title": "My BigQuery Destination",
    "destination_type": "google_bigquery",
    "destination_status": "active"
  }
}
```

### DataTable

Used by 10 events: `data_table_created`, `data_table_marked_as_deleting`, `extraction_added`, `table_auto_add_new_fields_changed`, `table_auto_extract_new_accounts_changed`, `table_extract_template_changed`, `table_freshness_changed`, `table_meta_set`, `table_sql_available_at_changed`, `table_title_changed`.

Example (`data_table_created`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "data_table_created",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "DataTable",
    "product_domain_event_class": "DataTableCreated",
    "product_domain_event_usecase": "CreateExtractionsByTemplateUsecase",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace",
    "datatable_id": "987654",
    "datatable_name": "ui=0f1e2d3c4b5a69788796a5b4c3d2e1f0",
    "datatable_title": "Facebook Ads - Ads Creative",
    "datasource_name": "facebook",
    "datatable_sql_name": "ads_creative_facebook_all_data"
  }
}
```

### Load

Used by 9 events: `error_changed`, `execution_policy_changed`, `load_completed`, `load_created`, `load_started`, `order_paused`, `order_started`, `run_policy_changed`, `schedules_changed`.

Example (`load_completed`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "load_completed",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "Load",
    "product_domain_event_class": "LoadCompleted",
    "product_domain_event_usecase": "LoadCompletedUseCase",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace",
    "load_destination_title": "My BigQuery Destination",
    "load_id": "112233",
    "order_id": "654321",
    "order_ui_link": "https://app.improvado.io/load_order/112233/11112222-3333-4444-5555-666677778888?workspace=1234"
  }
}
```

### Recipe

Used by 10 events: `recipe_activated`, `recipe_backward_compatibility_validated`, `recipe_backward_compatibility_validation_failed`, `recipe_backward_compatibility_validation_skipped`, `recipe_columns_validated`, `recipe_deactivated`, `recipe_promoted`, `recipe_validate_complexity_failed`, `recipe_validate_complexity_success`, `recipe_view_name_updated`.

Example (`recipe_activated`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "recipe_activated",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "recipe_event_is_impersonated": "0",
    "recipe_event_actor": "",
    "recipe_event_view_name": "",
    "recipe_event_old_view_name": "",
    "recipe_event_new_view_name": "",
    "recipe_event_error_message": "",
    "recipe_event_skip_reason": "",
    "recipe_event_is_manual_deactivation": "0",
    "recipe_event_description": "",
    "is_action_log": "1"
  }
}
```

### Transformation

Used by 3 events: `transformation_completed`, `transformation_created`, `transformation_started`.

Example (`transformation_completed`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "transformation_completed",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "Transformation",
    "product_domain_event_class": "TransformationCompleted",
    "product_domain_event_usecase": "CompleteTransformationUseCase",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace",
    "mcdm_recipe_title": "",
    "transformation_id": "445566",
    "order_id": "654321",
    "order_ui_link": "unknown",
    "start_reason": "",
    "run_id": "0f1e2d3c4b5a69788796a5b4c3d2e1f0"
  }
}
```

### Workspace

Used by 5 events: `user_added_to_workspace`, `user_removed_from_workspace`, `user_workspace_role_changed`, `workspace_connector_changed`, `workspace_created`.

Example (`workspace_created`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "workspace_created",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "Workspace",
    "product_domain_event_class": "WorkspaceCreated",
    "product_domain_event_usecase": "CreateOrUpdateAgencyUsecase",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace"
  }
}
```

### User

Used by 2 events: `user_deactivated`, `user_invited_to_workspaces`.

> This shape has never been observed in production — every event using it is currently silent. Treat it as indicative.

Example (`user_deactivated`):

```json
{
  "id": "A1B2C3D4E5F6789012345678ABCDEF90",
  "type": "user_deactivated",
  "timestamp": "2026-04-06 11:39:46.752",
  "data": {
    "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
    "product_domain_event_aggregate_class": "User",
    "product_domain_event_class": "UserDeactivated",
    "product_domain_event_usecase": "",
    "product_domain_event": "",
    "agency_title": "My Agency",
    "workspace_title": "Main Workspace"
  }
}
```

## Event catalog

Subscribe with the identifiers from `GET /api/v3/webhook_event_types/`. 17 of the 90 types are marked **silent**: they are valid subscriptions, but produced no events in a 30-day production sample — do not build a flow that waits on one.

### Account

| Event | Description | Shape | Status |
|---|---|---|---|
| `account_created` | Account "{account_reference}" was created for connection "{connection_reference}" | Account | **Silent** |
| `account_disabled` | Account "{account_reference}" was disabled | Account | **Silent** |
| `account_disabled_for_copied_connection` | Account {account_id} was disabled for copied connection {connection_id} | Account | **Silent** |
| `account_enabled` | Account "{account_reference}" was enabled | Account | Active |
| `account_enabled_for_copied_connection` | Account {account_id} was enabled for copied connection {connection_id} | Account | **Silent** |
| `account_item_changed` | Account "{account_reference}" item was changed | Account | Active |
| `account_name_changed` | Account "{account_reference}" name was changed to "{account_name}" | Account | Active |
| `enabled_for_embedded_extraction_changed` | Account "{account_reference}" embedded extraction status was changed | Account | Active |

### Agency

| Event | Description | Shape | Status |
|---|---|---|---|
| `agency_created` | Agency "{agency_reference}" was created | Agency | Active |
| `agency_is_test_changed` | Agency "{agency_reference}" test status was changed | Agency | Active |
| `agency_migrated_to_workspace_separated_schemas` | Agency "{agency_reference}" was migrated to workspace separated schemas | Agency | **Silent** |
| `agency_offboarded` | Agency "{agency_reference}" was offboarded with database {database_name} | Agency | Active |
| `agency_toggle` | Agency "{agency_reference}" was toggled | Agency | Active |

### Connection

| Event | Description | Shape | Status |
|---|---|---|---|
| `connection_accounts_update_error` | Connection "{connection_reference}" accounts update encountered error | Connection | Active |
| `connection_accounts_update_fail` | Connection "{connection_reference}" accounts update failed | Connection | Active |
| `connection_accounts_update_started` | Connection "{connection_reference}" accounts update was started for {data_source} | Connection | **Silent** |
| `connection_accounts_update_success` | Connection "{connection_reference}" accounts update succeeded for agency "{agency_reference}" | Connection | **Silent** |
| `connection_created` | Connection "{connection_reference}" was created for {data_source} by {connected_by} | Connection | **Silent** |
| `connection_deleted` | Connection "{connection_reference}" was deleted | Connection | Active |
| `connection_invalidated` | Connection "{connection_reference}" was invalidated | Connection | Active |
| `connection_privacy_updated` | Connection {connection_id} privacy was updated to {is_private} by {updated_by} | Connection | Active |
| `connection_reconnected` | Connection "{connection_reference}" was reconnected to {data_source} by {last_authorized_by} | Connection | **Silent** |

### Data table

| Event | Description | Shape | Status |
|---|---|---|---|
| `data_table_created` | Data table "{data_table_reference}" was created in {data_source} with title {title} | DataTable | Active |
| `data_table_marked_as_deleting` | Data table {data_table} was marked as deleting | DataTable | Active |
| `extraction_added` | Extraction "{extraction_reference}" was added to data table "{data_table_reference}" | DataTable | Active |
| `table_auto_add_new_fields_changed` | Data table "{data_table_reference}" auto add new fields setting was changed to {auto_add_new_fields} | DataTable | Active |
| `table_auto_extract_new_accounts_changed` | Data table "{data_table_reference}" auto extract new accounts setting was changed to {auto_extract_new_accounts} by user {user_changed_auto_extract_new_accounts_id} | DataTable | Active |
| `table_extract_template_changed` | Data table "{data_table_reference}" extract template was changed to {extract_template} | DataTable | Active |
| `table_freshness_changed` | Data table "{data_table_reference}" freshness was updated from {old_value} to {new_value} | DataTable | Active |
| `table_meta_set` | Data table "{data_table_reference}" metadata was updated with fields | DataTable | Active |
| `table_sql_available_at_changed` | Data table "{data_table_reference}" SQL availability was set at {sql_available_at} | DataTable | Active |
| `table_title_changed` | Data table "{data_table_reference}" title was changed to {title} | DataTable | Active |

### Destination

| Event | Description | Shape | Status |
|---|---|---|---|
| `create_load_changed` | Destination connection {destination_connection_title} auto-load for new tables changed to {create_load_for_new_tables} | DestinationConnection | Active |
| `destination_connection_changed` | Destination connection {destination_connection_title} settings updated for {destination_type} | DestinationConnection | Active |
| `destination_connection_check_run` | Destination connection {destination_connection_title} check started | DestinationConnection | Active |
| `destination_connection_created` | Destination connection {destination_connection_title} created for {destination_type} | DestinationConnection | Active |
| `destination_connection_deleted` | Destination connection {destination_connection_title} was deleted | DestinationConnection | **Silent** |
| `error_text_changed` | Destination connection {destination_connection_title} error: {error_text} | DestinationConnection | Active |
| `gbq_by_improvado_created` | Destination connection {connection_id} (Google BigQuery by Improvado) was created for {destination_type} | DestinationConnection | **Silent** |
| `gbq_by_improvado_for_sandbox_created` | Destination connection {destination_connection_title} (Google BigQuery sandbox) created by Improvado | DestinationConnection | **Silent** |
| `secret_key_changed` | Destination connection {destination_connection_title} credentials were updated | DestinationConnection | Active |
| `status_changed` | Destination connection {destination_connection_title} status changed to {status} | DestinationConnection | Active |
| `title_changed` | Destination connection renamed to {title} | DestinationConnection | Active |

### Extraction

| Event | Description | Shape | Status |
|---|---|---|---|
| `additional_params_changed` | Extraction "{extraction_reference}" additional parameters were changed | Extraction | Active |
| `custom_filters_changed` | Extraction {extraction_id} custom filters were changed to {custom_filters} | Extraction | **Silent** |
| `extraction_account_changed` | Extraction "{extraction_reference}" account was changed from {old_account_entity_id} to {new_account_entity_id} | Extraction | Active |
| `extraction_completed` | Extraction "{extraction_reference}" run completed with status {status} | Extraction | Active |
| `extraction_created` | Extraction "{extraction_reference}" was created for {data_source} with account {account_name} | Extraction | Active |
| `extraction_marked_as_deleting` | Extraction "{extraction_reference}" was marked as deleting | Extraction | Active |
| `extraction_paused` | Extraction order was paused. Reason: {pause_reason} | Extraction | Active |
| `extraction_schedules_changed` | Extraction "{extraction_reference}" schedules were changed | Extraction | Active |
| `extraction_template_changed` | Extraction "{extraction_reference}" template was changed from {old_extract_template} to {new_extract_template} | Extraction | Active |
| `extraction_unpaused` | Extraction order was unpaused. Reason: {unpause_reason} | Extraction | Active |
| `fields_changed` | Extraction "{extraction_reference}" fields were changed | Extraction | Active |
| `historical_download_started` | Historical download was started for extraction "{extraction_reference}" | Extraction | Active |
| `regular_download_started` | Regular download was started for extraction "{extraction_reference}" | Extraction | Active |
| `sync_historical_data_changed` | Extraction "{extraction_reference}" sync historical data was changed to {sync_historical_data} | Extraction | Active |

### Invite

| Event | Description | Shape | Status |
|---|---|---|---|
| `agency_invite_created` | Invite to agency for {dts_invitee_user_email} created | AgencyInvite | **Silent** |
| `invite_accepted` | Invite to agency accepted by {dts_invitee_user_email} | AgencyInvite | Active |
| `invite_deleted` | Invite to agency deleted | AgencyInvite | **Silent** |
| `invite_sent` | Invite to agency sent to {dts_invitee_user_email} for workspace {dts_workspace_title} | AgencyInvite | Active |

### Load

| Event | Description | Shape | Status |
|---|---|---|---|
| `error_changed` | Load order "{load_reference}" error status updated to: "{error}" | Load | Active |
| `execution_policy_changed` | Load order "{load_reference}" execution policy changed to {execution_policy} | Load | Active |
| `load_completed` | Load order "{load_reference}" completed with status {status}: {total_rows} rows | Load | Active |
| `load_created` | Load order "{load_reference}" was created | Load | Active |
| `load_started` | Load order "{load_reference}" started (reason: {start_reason}) | Load | Active |
| `order_paused` | Load order "{load_reference}" was paused | Load | Active |
| `order_started` | Load order "{load_reference}" was started | Load | Active |
| `run_policy_changed` | Load order "{load_reference}" run policy changed to {run_policy} | Load | Active |
| `schedules_changed` | Load order "{load_reference}" schedules were updated | Load | Active |

### Recipe

| Event | Description | Shape | Status |
|---|---|---|---|
| `recipe_activated` | — | Recipe | Active |
| `recipe_backward_compatibility_validated` | — | Recipe | Active |
| `recipe_backward_compatibility_validation_failed` | — | Recipe | Active |
| `recipe_backward_compatibility_validation_skipped` | — | Recipe | Active |
| `recipe_columns_validated` | — | Recipe | Active |
| `recipe_deactivated` | — | Recipe | Active |
| `recipe_promoted` | — | Recipe | Active |
| `recipe_validate_complexity_failed` | — | Recipe | Active |
| `recipe_validate_complexity_success` | — | Recipe | Active |
| `recipe_view_name_updated` | — | Recipe | Active |

### Transformation

| Event | Description | Shape | Status |
|---|---|---|---|
| `transformation_completed` | MCDM Transformation "{transformation_reference}" completed | Transformation | Active |
| `transformation_created` | MCDM Transformation "{transformation_reference}" was created | Transformation | Active |
| `transformation_started` | MCDM Transformation "{transformation_reference}" was started | Transformation | Active |

### User

| Event | Description | Shape | Status |
|---|---|---|---|
| `user_deactivated` | User "{user_reference}" was deactivated | User | **Silent** |
| `user_invited_to_workspaces` | User "{user_reference}" was invited to workspaces by {invitor_id} | User | **Silent** |

### Workspace

| Event | Description | Shape | Status |
|---|---|---|---|
| `user_added_to_workspace` | User "{user_reference}" was added to workspace "{workspace_reference}" with role {role} | Workspace | Active |
| `user_removed_from_workspace` | User "{user_reference}" was removed from workspace "{workspace_reference}" | Workspace | Active |
| `user_workspace_role_changed` | User "{user_reference}" role was changed to {role} in workspace "{workspace_reference}" | Workspace | Active |
| `workspace_connector_changed` | Workspace "{workspace_reference}" storage schema was changed to {storage_schema_name} | Workspace | Active |
| `workspace_created` | Workspace "{workspace_reference}" was created for agency "{agency_reference}" | Workspace | Active |