> For the complete documentation index, see [llms.txt](https://developers.make.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.make.com/event-subscription/reference/event-types.md).

# Event types

Use `type` to route the event and `{type, version}` to identify its payload schema.

All currently documented event subscription payloads use version `1`. The version belongs to an individual event type; it is not a global Make API version.

Your parser should:

* route on `type`
* confirm that your integration supports the received `{type, version}` before interpreting `data`
* require the documented fields for the selected schema
* tolerate additional fields it does not use
* [handle an unknown type or version explicitly](https://developers.make.com/event-subscription/implementation/handle-unknown-events.md)

## Common envelope <a href="#common-envelope" id="common-envelope"></a>

| Field       | Type                 | Required | Description                                |
| ----------- | -------------------- | -------- | ------------------------------------------ |
| `type`      | string               | yes      | Event type discriminator.                  |
| `timestamp` | string (`date-time`) | yes      | UTC date and time when the event occurred. |
| `version`   | integer              | yes      | Schema version for this event type.        |
| `data`      | object               | yes      | Event-specific payload.                    |

`Webhook-Topic` repeats the current event type as delivery metadata. Use the body `type` as the canonical value for payload dispatch.

## Catalog <a href="#catalog" id="catalog"></a>

### Scenario-level events <a href="#scenario-level-events" id="scenario-level-events"></a>

| Event                                                                                                                                  | Version | Occurs when                                       |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- |
| [`execution.failed`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/executionfailed)                   | `1`     | A scenario execution reports an error or warning. |
| [`scenario.activated`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/scenarioactivated)               | `1`     | Scenario scheduling is turned on.                 |
| [`scenario.created`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/scenariocreated)                   | `1`     | A scenario is created.                            |
| [`scenario.deactivated`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/scenariodeactivated)           | `1`     | Scenario scheduling is turned off.                |
| [`scenario.restored`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/scenariorestored)                 | `1`     | A scenario is restored from trash.                |
| [`scenario.settings_updated`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/scenariosettings_updated) | `1`     | A supported scenario setting changes.             |
| [`scenario.updated`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/scenarioupdated)                   | `1`     | A scenario is updated.                            |

### Organization-level events <a href="#organization-level-events" id="organization-level-events"></a>

| Event                                                                                                                      | Version | Occurs when                     |
| -------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------- |
| [`custom_role.created`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/custom_rolecreated) | `1`     | A custom role is created.       |
| [`custom_role.deleted`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/custom_roledeleted) | `1`     | A custom role is deleted.       |
| [`custom_role.updated`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/custom_roleupdated) | `1`     | A custom role is updated.       |
| [`team.created`](https://reports.app.mkhq.io/r/9efa52e6-90f7-49c7-bab5-7cd1821459b3#event-types/teamcreated)               | `1`     | A non-personal team is created. |

## `execution.failed` <a href="#executionfailed" id="executionfailed"></a>

Occurs when a scenario execution reports an error or warning. Check `status` to distinguish the two outcomes.

### Example <a href="#example" id="example"></a>

```json
{
  "type": "execution.failed",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "execution_id": "exec-123",
    "organization_id": 100,
    "team_id": 7,
    "scenario_id": 999,
    "app_name": "HTTP",
    "module_name": "Make a request",
    "exception_type": "RuntimeError",
    "message": "Something went wrong",
    "status": "error",
    "trigger": {
      "type": "manual",
      "user_id": 42
    }
  }
}
```

### `data` fields <a href="#data-fields" id="data-fields"></a>

| Field             | Type    | Required | Description                                                                        |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------- |
| `execution_id`    | string  | yes      | Unique execution ID. Do not assume a UUID format.                                  |
| `organization_id` | integer | yes      | ID of the organization.                                                            |
| `team_id`         | integer | yes      | ID of the team.                                                                    |
| `scenario_id`     | integer | yes      | ID of the scenario.                                                                |
| `app_name`        | string  | no       | Name of the app associated with the error or warning. Omitted when unavailable.    |
| `module_name`     | string  | no       | Name of the module associated with the error or warning. Omitted when unavailable. |
| `exception_type`  | string  | yes      | Exception class name, such as `RuntimeError` or `DataError`.                       |
| `message`         | string  | yes      | Error or warning message.                                                          |
| `status`          | string  | yes      | `error` or `warning`.                                                              |
| `trigger`         | object  | yes      | How the execution was triggered. See the variants below.                           |

### `trigger` variants <a href="#trigger-variants" id="trigger-variants"></a>

For a manual execution:

```json
{
  "type": "manual",
  "user_id": 42
}
```

| Field     | Type    | Required | Description                                 |
| --------- | ------- | -------- | ------------------------------------------- |
| `type`    | string  | yes      | Always `manual`.                            |
| `user_id` | integer | yes      | ID of the user who triggered the execution. |

For an automatically triggered execution, such as one started by a schedule or webhook:

```json
{
  "type": "auto"
}
```

| Field  | Type   | Required | Description    |
| ------ | ------ | -------- | -------------- |
| `type` | string | yes      | Always `auto`. |

## `scenario.activated` <a href="#scenarioactivated" id="scenarioactivated"></a>

Occurs when scenario scheduling is turned on. It does not indicate that an individual scenario execution has started.

### Example <a href="#example-2" id="example-2"></a>

```json
{
  "type": "scenario.activated",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "scenario_id": 999,
    "user_id": 42,
    "team_id": 7,
    "organization_id": 100
  }
}
```

### `data` fields <a href="#data-fields-2" id="data-fields-2"></a>

| Field             | Type    | Required | Description                                    |
| ----------------- | ------- | -------- | ---------------------------------------------- |
| `scenario_id`     | integer | yes      | ID of the activated scenario.                  |
| `user_id`         | integer | yes      | ID of the user who activated the scenario.     |
| `team_id`         | integer | yes      | ID of the team that contains the scenario.     |
| `organization_id` | integer | yes      | ID of the organization that contains the team. |

## `scenario.created` <a href="#scenariocreated" id="scenariocreated"></a>

Occurs when a scenario is created.

### Example <a href="#example-3" id="example-3"></a>

```json
{
  "type": "scenario.created",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "scenario_id": 999,
    "user_id": 42,
    "team_id": 7,
    "organization_id": 100
  }
}
```

### `data` fields <a href="#data-fields-3" id="data-fields-3"></a>

| Field             | Type    | Required | Description                                                 |
| ----------------- | ------- | -------- | ----------------------------------------------------------- |
| `scenario_id`     | integer | yes      | ID of the created scenario.                                 |
| `user_id`         | integer | yes      | ID of the user associated with the scenario creation event. |
| `team_id`         | integer | yes      | ID of the team that contains the scenario.                  |
| `organization_id` | integer | yes      | ID of the organization that contains the team.              |

## `scenario.deactivated` <a href="#scenariodeactivated" id="scenariodeactivated"></a>

Occurs when scenario scheduling is turned off. It does not indicate that an individual scenario execution has ended.

### Example <a href="#example-4" id="example-4"></a>

```json
{
  "type": "scenario.deactivated",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "scenario_id": 999,
    "actor": {
      "type": "user",
      "user_id": 42
    },
    "team_id": 7,
    "organization_id": 100
  }
}
```

### `data` fields <a href="#data-fields-4" id="data-fields-4"></a>

| Field             | Type    | Required | Description                                                           |
| ----------------- | ------- | -------- | --------------------------------------------------------------------- |
| `scenario_id`     | integer | yes      | ID of the deactivated scenario.                                       |
| `actor`           | object  | yes      | User or system that deactivated the scenario. See the variants below. |
| `team_id`         | integer | yes      | ID of the team that contains the scenario.                            |
| `organization_id` | integer | yes      | ID of the organization that contains the team.                        |

### `actor` variants <a href="#actor-variants" id="actor-variants"></a>

For an action associated with a user:

```json
{
  "type": "user",
  "user_id": 42
}
```

For a system action:

```json
{
  "type": "system"
}
```

| Field     | Type    | Required        | Description                                |
| --------- | ------- | --------------- | ------------------------------------------ |
| `type`    | string  | yes             | `user` or `system`.                        |
| `user_id` | integer | only for `user` | ID of the user associated with the action. |

## `scenario.restored` <a href="#scenariorestored" id="scenariorestored"></a>

Occurs when a scenario is restored from trash.

### Example <a href="#example-5" id="example-5"></a>

```json
{
  "type": "scenario.restored",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "scenario_id": 999,
    "user_id": 42,
    "team_id": 7,
    "organization_id": 100
  }
}
```

### `data` fields <a href="#data-fields-5" id="data-fields-5"></a>

| Field             | Type    | Required | Description                                    |
| ----------------- | ------- | -------- | ---------------------------------------------- |
| `scenario_id`     | integer | yes      | ID of the restored scenario.                   |
| `user_id`         | integer | yes      | ID of the user who restored the scenario.      |
| `team_id`         | integer | yes      | ID of the team that contains the scenario.     |
| `organization_id` | integer | yes      | ID of the organization that contains the team. |

## `scenario.settings_updated` <a href="#scenariosettings_updated" id="scenariosettings_updated"></a>

Occurs once for each supported scenario setting whose value changes. The event identifies the setting and provides its previous and new values. The same update can also produce `scenario.updated`.

### Example <a href="#example-6" id="example-6"></a>

```json
{
  "type": "scenario.settings_updated",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "scenario_id": 999,
    "user_id": 42,
    "team_id": 7,
    "organization_id": 100,
    "setting": {
      "setting_key": "maxErrors",
      "setting_description": "Number of consecutive errors",
      "old_value": 3,
      "new_value": 5
    }
  }
}
```

### `data` fields <a href="#data-fields-6" id="data-fields-6"></a>

| Field             | Type    | Required | Description                                    |
| ----------------- | ------- | -------- | ---------------------------------------------- |
| `scenario_id`     | integer | yes      | ID of the updated scenario.                    |
| `user_id`         | integer | yes      | ID of the user who changed the setting.        |
| `team_id`         | integer | yes      | ID of the team that contains the scenario.     |
| `organization_id` | integer | yes      | ID of the organization that contains the team. |
| `setting`         | object  | yes      | Setting that changed.                          |

### `setting` fields <a href="#setting-fields" id="setting-fields"></a>

| Field                 | Type               | Required | Description                                                     |
| --------------------- | ------------------ | -------- | --------------------------------------------------------------- |
| `setting_key`         | string             | yes      | Setting identifier. See the supported values below.             |
| `setting_description` | string             | no       | Display description of the setting. Omitted when unavailable.   |
| `old_value`           | integer or boolean | yes      | Value before the change. Its type corresponds to `setting_key`. |
| `new_value`           | integer or boolean | yes      | Value after the change. Its type corresponds to `setting_key`.  |

Numeric setting keys use integer values:

* `roundtrips`
* `maxErrors`

Boolean setting keys use boolean values:

* `autoCommit`
* `autoCommitTriggerLast`
* `sequential`
* `confidential`
* `dataloss`
* `dlq`
* `freshVariables`

## `scenario.updated` <a href="#scenarioupdated" id="scenarioupdated"></a>

Occurs when a user updates a scenario, including changes to its name, description, scheduling, blueprint, metadata, type, slots, or folder. The payload identifies the scenario and actor but does not identify which fields changed.

### Example <a href="#example-7" id="example-7"></a>

```json
{
  "type": "scenario.updated",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "scenario_id": 999,
    "actor": {
      "type": "user",
      "user_id": 42
    },
    "team_id": 7,
    "organization_id": 100
  }
}
```

### `data` fields <a href="#data-fields-7" id="data-fields-7"></a>

| Field             | Type    | Required | Description                                                        |
| ----------------- | ------- | -------- | ------------------------------------------------------------------ |
| `scenario_id`     | integer | yes      | ID of the updated scenario.                                        |
| `actor`           | object  | yes      | User or system associated with the update. See the variants below. |
| `team_id`         | integer | yes      | ID of the team that contains the scenario.                         |
| `organization_id` | integer | yes      | ID of the organization that contains the team.                     |

### `actor` variants <a href="#actor-variants-2" id="actor-variants-2"></a>

For an update associated with a user:

```json
{
  "type": "user",
  "user_id": 42
}
```

For a system update:

```json
{
  "type": "system"
}
```

| Field     | Type    | Required        | Description                                |
| --------- | ------- | --------------- | ------------------------------------------ |
| `type`    | string  | yes             | `user` or `system`.                        |
| `user_id` | integer | only for `user` | ID of the user associated with the update. |

## `custom_role.created` <a href="#custom_rolecreated" id="custom_rolecreated"></a>

Occurs when a custom role is created in an organization.

### Example <a href="#example-8" id="example-8"></a>

```json
{
  "type": "custom_role.created",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "organization_id": 100,
    "user_id": 42,
    "role_id": 501,
    "role_name": "Automation operator",
    "role_type": "organization",
    "description": "Can operate production scenarios",
    "permissions": [
      {
        "permission_id": 12,
        "permission_display_name": "scenario run"
      }
    ]
  }
}
```

### `data` fields <a href="#data-fields-8" id="data-fields-8"></a>

| Field             | Type    | Required | Description                                               |
| ----------------- | ------- | -------- | --------------------------------------------------------- |
| `organization_id` | integer | yes      | ID of the organization.                                   |
| `user_id`         | integer | yes      | ID of the user who created the role.                      |
| `role_id`         | integer | yes      | ID of the custom role.                                    |
| `role_name`       | string  | yes      | Name of the custom role.                                  |
| `role_type`       | string  | yes      | `organization` or `team`.                                 |
| `description`     | string  | no       | Description of the role. Omitted when none is set.        |
| `permissions`     | array   | yes      | Permissions assigned to the role. The array can be empty. |

Each object in `permissions` has the following fields:

| Field                     | Type    | Required | Description                     |
| ------------------------- | ------- | -------- | ------------------------------- |
| `permission_id`           | integer | yes      | ID of the permission.           |
| `permission_display_name` | string  | yes      | Display name of the permission. |

## `custom_role.deleted` <a href="#custom_roledeleted" id="custom_roledeleted"></a>

Occurs when a custom role is deleted from an organization.

### Example <a href="#example-9" id="example-9"></a>

```json
{
  "type": "custom_role.deleted",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "organization_id": 100,
    "user_id": 42,
    "role_id": 501,
    "role_name": "Automation operator",
    "role_type": "organization"
  }
}
```

### `data` fields <a href="#data-fields-9" id="data-fields-9"></a>

| Field             | Type    | Required | Description                          |
| ----------------- | ------- | -------- | ------------------------------------ |
| `organization_id` | integer | yes      | ID of the organization.              |
| `user_id`         | integer | yes      | ID of the user who deleted the role. |
| `role_id`         | integer | yes      | ID of the deleted custom role.       |
| `role_name`       | string  | yes      | Name of the deleted custom role.     |
| `role_type`       | string  | yes      | `organization` or `team`.            |

## `custom_role.updated` <a href="#custom_roleupdated" id="custom_roleupdated"></a>

Occurs when a custom role is updated in an organization.

### Example <a href="#example-10" id="example-10"></a>

```json
{
  "type": "custom_role.updated",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "organization_id": 100,
    "user_id": 42,
    "role_id": 501,
    "role_name": "Senior automation operator",
    "role_name_previous": "Automation operator",
    "role_type": "organization",
    "description": "Can operate and edit production scenarios",
    "permissions_added": [
      {
        "permission_id": 13,
        "permission_display_name": "scenario edit"
      }
    ],
    "permissions_removed": []
  }
}
```

### `data` fields <a href="#data-fields-10" id="data-fields-10"></a>

| Field                 | Type           | Required | Description                                                |
| --------------------- | -------------- | -------- | ---------------------------------------------------------- |
| `organization_id`     | integer        | yes      | ID of the organization.                                    |
| `user_id`             | integer        | yes      | ID of the user who updated the role.                       |
| `role_id`             | integer        | yes      | ID of the custom role.                                     |
| `role_name`           | string         | yes      | Current name of the custom role.                           |
| `role_name_previous`  | string         | no       | Previous name of the role. Present when the name changed.  |
| `role_type`           | string         | yes      | `organization` or `team`.                                  |
| `description`         | string or null | yes      | Current role description, or `null` if none is set.        |
| `permissions_added`   | array          | yes      | Permissions added by the update. The array can be empty.   |
| `permissions_removed` | array          | yes      | Permissions removed by the update. The array can be empty. |

Each object in `permissions_added` and `permissions_removed` has the following fields:

| Field                     | Type    | Required | Description                     |
| ------------------------- | ------- | -------- | ------------------------------- |
| `permission_id`           | integer | yes      | ID of the permission.           |
| `permission_display_name` | string  | yes      | Display name of the permission. |

## `team.created` <a href="#teamcreated" id="teamcreated"></a>

Occurs when a non-personal team is created in an organization. Personal teams do not produce this event.

### Example <a href="#example-11" id="example-11"></a>

```json
{
  "type": "team.created",
  "timestamp": "2026-09-30T12:00:00.000Z",
  "version": 1,
  "data": {
    "organization_id": 100,
    "team_id": 7,
    "user_creator_id": 42,
    "team_type": "standard",
    "owner_user_id": 42
  }
}
```

### `data` fields <a href="#data-fields-11" id="data-fields-11"></a>

| Field             | Type            | Required | Description                                                              |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------------ |
| `organization_id` | integer         | yes      | ID of the organization that contains the team.                           |
| `team_id`         | integer         | yes      | ID of the created team.                                                  |
| `user_creator_id` | integer         | yes      | ID of the user who created the team.                                     |
| `team_type`       | string          | no       | Team classification: `standard` or `personal`. Omitted when unavailable. |
| `owner_user_id`   | integer or null | yes      | ID of the team owner, or `null` when the team has no owner.              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.make.com/event-subscription/reference/event-types.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
