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. For example, to listen for any kind of change:

change.*

Or just to listen 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 were 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.