---
title: Events
slug: event-notifications
docTags: 
createdAt: 2021-04-16T16:13:13.000Z
---

Any alteration to data on ChartHop represents an *event*.

You can retrieve events with the Event API, or set an app web hook to subscribe to an event pattern. Note that events are not exactly the same as *changes* (such as hires or departures), because an event can represent an amendment, or even a cancellation, of a change.

For example, if a new hire is entered, and then the date of that new hire is altered, this is just one new-hire *change*, but it's two *events*: change.create.hire and change.update.hire.

In general an event consists of an *entity* (the thing that is being acted upon), and a *type* (the type of action that is happening to the entity). In some cases the event has a *subtype* which further describes the type of entity. All events have a code that consists of either `entity.type` or `entity.type.subtype`

## Events List

### Changes

| Event                  | Meaning                          |
| ---------------------- | -------------------------------- |
| `change.create.create` | New job created                  |
| `change.create.update` | Job updated                      |
| `change.create.hire`   | New hire                         |
| `change.create.depart` | Departure                        |
| `change.create.move`   | Move/transfer                    |
| `change.create.delete` | Job removed                      |
| `change.create.data`   | Data collected                   |
| `change.update.create` | Amendment to previous new job    |
| `change.update.update` | Amendment to previous job update |
| `change.update.hire`   | Amendment to hire                |
| `change.update.depart` | Amendment to departure           |
| `change.update.move`   | Amendment to move                |
| `change.update.delete` | Amendment to job removal         |
| `change.update.data`   | Amendment to collected data      |
| `change.delete.create` | Cancellation of job creation     |
| `change.delete.update` | Cancellation of job update       |
| `change.delete.hire`   | Cancellation of new hire         |
| `change.delete.depart` | Cancellation of departure        |
| `change.delete.move`   | Cancellation of move             |
| `change.delete.delete` | Cancellation of deletion         |
| `change.delete.data`   | Cancellation of collected data   |

### People & Jobs

| Event                        | Meaning            |
| ---------------------------- | ------------------ |
| `job.create` `person.create` | New person created |
| `person.update`              | Person updated     |
| `job.update`                 | Job updated        |
| `job.delete`                 | Job deleted        |

### Groups

| Event          | Meaning       |
| -------------- | ------------- |
| `group.create` | Group created |
| `group.update` | Group updated |
| `group.delete` | Group deleted |

### Goals

| Event                  | Meaning                       |
| ---------------------- | ----------------------------- |
| `goal.create`          | Goal created                  |
| `goal.update`          | Goal updated                  |
| `goal.delete`          | Goal deleted                  |
| `goal_progress.create` | Goal progress update added    |
| `goal_progress.update` | Goal progress update modified |
| `goal_progress.delete` | Goal progress update deleted  |

### AI

| Event                    | Meaning                  |
| ------------------------ | ------------------------ |
| `ai_chat.create`         | AI chat started          |
| `ai_chat.update`         | AI chat updated          |
| `ai_chat.delete`         | AI chat deleted          |
| `ai_agent.create`        | AI agent created         |
| `ai_agent.update`        | AI agent updated         |
| `ai_agent.delete`        | AI agent deleted         |
| `ai_agent_memory.create` | AI agent memory created  |
| `ai_agent_memory.update` | AI agent memory updated  |
| `ai_agent_memory.delete` | AI agent memory deleted  |
| `ai_config.update`       | AI configuration updated |
| `ai_hint.create`         | AI hint created          |
| `ai_hint.update`         | AI hint updated          |
| `ai_hint.delete`         | AI hint deleted          |
| `ai_prompt.create`       | AI prompt created        |
| `ai_prompt.update`       | AI prompt updated        |
| `ai_prompt.delete`       | AI prompt deleted        |
| `ai_credit_limit.update` | AI credit limit updated  |

### Approvals

| Event                         | Meaning                      |
| ----------------------------- | ---------------------------- |
| `approval_chain.create`       | Approval chain created       |
| `approval_chain.update`       | Approval chain updated       |
| `approval_chain.delete`       | Approval chain deleted       |
| `approval_chain_stage.create` | Approval chain stage created |
| `approval_chain_stage.update` | Approval chain stage updated |
| `approval_chain_stage.delete` | Approval chain stage deleted |
| `approval_request.create`     | Approval request submitted   |
| `approval_request.approve`    | Approval request approved    |
| `approval_request.reject`     | Approval request rejected    |
| `approval_request.update`     | Approval request updated     |
| `approval_delegate.create`    | Approval delegation created  |
| `approval_delegate.update`    | Approval delegation updated  |
| `approval_delegate.delete`    | Approval delegation deleted  |

### Compensation

| Event                | Meaning                        |
| -------------------- | ------------------------------ |
| `comp_band.create`   | Compensation band created      |
| `comp_band.update`   | Compensation band updated      |
| `comp_band.delete`   | Compensation band deleted      |
| `comp_review.create` | Compensation review created    |
| `comp_review.update` | Compensation review updated    |
| `comp_review.delete` | Compensation review deleted    |
| `budget.create`      | Budget created                 |
| `budget.update`      | Budget updated                 |
| `budget.delete`      | Budget deleted                 |
| `budget_pool.create` | Budget pool created            |
| `budget_pool.update` | Budget pool updated            |
| `budget_pool.delete` | Budget pool deleted            |
| `guideline.create`   | Compensation guideline created |
| `guideline.update`   | Compensation guideline updated |
| `guideline.delete`   | Compensation guideline deleted |

### Equity

| Event                | Meaning             |
| -------------------- | ------------------- |
| `stock_grant.create` | Stock grant created |
| `stock_grant.update` | Stock grant updated |
| `stock_grant.delete` | Stock grant deleted |
| `stock_price.update` | Stock price updated |

### Time Off

| Event                   | Meaning                  |
| ----------------------- | ------------------------ |
| `timeoff.create`        | Time off request created |
| `timeoff.update`        | Time off request updated |
| `timeoff.delete`        | Time off request deleted |
| `timeoff_policy.create` | Time off policy created  |
| `timeoff_policy.update` | Time off policy updated  |
| `timeoff_policy.delete` | Time off policy deleted  |

### Calendar

| Event                   | Meaning                |
| ----------------------- | ---------------------- |
| `calendar.create`       | Calendar created       |
| `calendar.update`       | Calendar updated       |
| `calendar.delete`       | Calendar deleted       |
| `calendar_entry.create` | Calendar entry created |
| `calendar_entry.update` | Calendar entry updated |
| `calendar_entry.delete` | Calendar entry deleted |

### Tasks

| Event                | Meaning                    |
| -------------------- | -------------------------- |
| `task.create`        | Task created               |
| `task.update`        | Task updated               |
| `task.delete`        | Task deleted               |
| `task_config.create` | Task configuration created |
| `task_config.update` | Task configuration updated |
| `task_config.delete` | Task configuration deleted |

### Forms

| Event                  | Meaning               |
| ---------------------- | --------------------- |
| `form.create`          | Custom form created   |
| `form.update`          | Custom form updated   |
| `form.delete`          | Custom form deleted   |
| `form.submit`          | Custom form submitted |
| `form_response.create` | Form response created |
| `form_response.update` | Form response updated |
| `form_response.delete` | Form response deleted |

### Policies

| Event           | Meaning        |
| --------------- | -------------- |
| `policy.create` | Policy created |
| `policy.update` | Policy updated |
| `policy.delete` | Policy deleted |

### Roles & Access

| Event                   | Meaning                           |
| ----------------------- | --------------------------------- |
| `role.create`           | Role created                      |
| `role.update`           | Role updated                      |
| `role.delete`           | Role deleted                      |
| `user.create`           | User created                      |
| `user.update`           | User updated                      |
| `user.create.<appname>` | App installed                     |
| `user.update.<appname>` | Installed app settings changed    |
| `user.token.<appname>`  | Token generated for installed app |
| `user.delete.<appname>` | App uninstalled                   |
| `user.update_password`  | User password updated             |
| `user.remove_password`  | User password removed             |
| `user.invite`           | User invited into org             |

### Apps & Integrations

| Event        | Meaning     |
| ------------ | ----------- |
| `app.create` | App created |
| `app.update` | App updated |
| `app.delete` | App deleted |

### Scenarios

| Event             | Meaning          |
| ----------------- | ---------------- |
| `scenario.create` | Scenario created |
| `scenario.update` | Scenario updated |
| `scenario.delete` | Scenario deleted |

### Tables

| Event              | Meaning              |
| ------------------ | -------------------- |
| `table.create`     | Custom table created |
| `table.update`     | Custom table updated |
| `table.delete`     | Custom table deleted |
| `table_row.create` | Table row created    |
| `table_row.update` | Table row updated    |
| `table_row.delete` | Table row deleted    |

### Transcripts

| Event               | Meaning                    |
| ------------------- | -------------------------- |
| `transcript.create` | Meeting transcript created |
| `transcript.update` | Meeting transcript updated |
| `transcript.delete` | Meeting transcript deleted |

### Content & Reports

| Event                 | Meaning              |
| --------------------- | -------------------- |
| `content.create`      | Content created      |
| `content.update`      | Content updated      |
| `content.delete`      | Content deleted      |
| `report.create`       | Report created       |
| `report.update`       | Report updated       |
| `report.delete`       | Report deleted       |
| `report_chart.create` | Report chart created |
| `report_chart.update` | Report chart updated |
| `report_chart.delete` | Report chart deleted |
| `profile_tab.create`  | Profile tab created  |
| `profile_tab.update`  | Profile tab updated  |
| `profile_tab.delete`  | Profile tab deleted  |

### Fields & Configuration

| Event              | Meaning              |
| ------------------ | -------------------- |
| `field.create`     | Custom field created |
| `field.update`     | Custom field updated |
| `field.delete`     | Custom field deleted |
| `job_code.create`  | Job code created     |
| `job_code.update`  | Job code updated     |
| `job_code.delete`  | Job code deleted     |
| `job_level.create` | Job level created    |
| `job_level.update` | Job level updated    |
| `job_level.delete` | Job level deleted    |

### Media & Files

| Event          | Meaning              |
| -------------- | -------------------- |
| `media.create` | Media image uploaded |
| `file.create`  | File uploaded        |
| `file.update`  | File updated         |
| `file.delete`  | File deleted         |

### Org

| Event        | Meaning              |
| ------------ | -------------------- |
| `org.create` | Org created          |
| `org.update` | Org settings updated |

### Processes

| Event                            | Meaning           |
| -------------------------------- | ----------------- |
| `process.create.<processname>`   | Process started   |
| `process.complete.<processname>` | Process completed |
| `process.error.<processname>`    | Process errored   |

### Comments

| Event            | Meaning         |
| ---------------- | --------------- |
| `comment.create` | Comment posted  |
| `comment.delete` | Comment deleted |

***

## Event Notifications

An app can subscribe to a pattern of events and receive them as a webhook.

For example:

You might build an app that takes an action upon a new hire. The app might listen for **change.create.hire** events. Whenever a hire occurs, there will be a POST to the app's event notification URL.

### Matching specific events

The app can match on different types of events via wildcard matching.

A few examples:

To listen for any kind of change:

`change.*`

To listen for any event involving a hire (new hire, amendment, or cancellation):

`change.*.hire`

### Filtering

For events of type `change.*` and `person.*`, you can add additional filtering based on any CQL Filter.

To add the filter, put the filter in `[brackets]` following the wildcard match.

For example, rather than listening for any new hire, you might only want to listen for new hires who are managers in the Engineering department. You could match on:

`change.create.hire [department:engineering directs > 0]`

The particular set of filters that are matched will be passed in the webhook in the matchFilters property.

### Webhook format and payload

You will receive the POST as an HTTP POST containing the following:

```json
{
    "id": <event id>,
    "orgId": <your org id>,
    "userId": <user id who caused the event>,
    "userName": <name of user who caused the event>,
    "appId": <id of app subscribing>,
    "appName": <name of app subscribing>,
    "appUserId": <id of installation of app>,
    "notifyUrl": <url of notification webhook>,
    "type": <event type>,
    "subtype": <event subtype>,
    "entityType": <entity type>,
    "entityId": <entity id>,
    "matchFilters": <list of filters matched>
    "at": <timestamp of event>
    "payload": <payload>,
}
```

The payload will vary depending on the type of event. Generally, for `create` events, the payload will contain the initial entity being created, and for `update` events the payload will contain the fields that were modified.

### Custom payloads

You can define custom payloads to control which specific data gets passed along. For example, you might want a webhook to receive the work email address of new hires.

Custom payloads may currently only be used for `change.*` events.

Define the payload as a JSON object, where the key represents the key element, and the value is a CQL expression containing the data you want to evaluate.

For example, let's suppose you want to pass along a new hire's work email, department name, whether or not they are a manager, and whether they are highly compensated. Set custom payload to:

```json
{
    "email": "contact.workEmail",
    "department": "department.name",
    "isManager": "directs > 0",
    "isHighlyCompensated": "base > 200000"
}    
```

Carefully considered custom payloads can allow you to control the information that leaves the system.