Events

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:

{
    "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:

{
    "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.