11min

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

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

person.create

New person created

person.update

Person updated

group.create

Group created

group.update

Group updated

group.delete

Group deleted

app.create

App created

app.update

App updated

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

comment.create

Comment posted

comment.delete

Comment deleted

content.create

Content created

content.update

Content updated

content.delete

Content deleted

field.create

Custom field created

field.update

Custom field updated

field.delete

Custom field deleted

form.create

Custom form created

form.update

Custom form updated

form.delete

Custom form deleted

media.create

Media image uploaded

org.create

Org created

org.update

Org settings updated

process.create.<processname>

Process started

process.complete.<processname>

Process completed

process.error.<processname>

Process errored

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

scenario.create

Scenario created

scenario.update

Scenario updated

scenario.delete

Scenario 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 only for hires:

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
|

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
|

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

ÔĽŅ

ÔĽŅ