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 for how to register and verify an endpoint.
Envelope
Every delivery is an HTTP POST with the same outer shape:
Code
| 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):
Code
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):
Code
Agency
Used by 5 events: agency_created, agency_is_test_changed, agency_migrated_to_workspace_separated_schemas, agency_offboarded, agency_toggle.
Example (agency_created):
Code
AgencyInvite
Used by 4 events: agency_invite_created, invite_accepted, invite_deleted, invite_sent.
Example (invite_sent):
Code
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):
Code
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):
Code
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):
Code
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):
Code
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):
Code
Transformation
Used by 3 events: transformation_completed, transformation_created, transformation_started.
Example (transformation_completed):
Code
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):
Code
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):
Code
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 |