Skip to main content
When a person joins, changes or leaves, andteam records an employee event. Two things read the same record: GET /v1/events, for a consumer that polls, and webhooks, for one that listens.

​
Effective, not entered

A dated change, such as a start date or a job change on its effective date, is written when it takes effect, not when it was entered. A promotion entered in January for 1 March is an event on 1 March. So an event is what is true now, and a consumer never has to hold a future change back.

​
The outbox

Events are written to an outbox in the same step as the change itself, so a change that is made always has its event, and an event never describes a change that was not made. Each event is then published once it takes effect: occurredAt is when the change was recorded, publishedAt is when it took effect and the event became readable.

​
The feed

since filters on publishedAt. The feed pages like any other list: see Pagination. It needs the Directory group, and changedFields names only fields the key’s groups open.

​
Ordering and duplicates

Every event has an id, and a sequence: per person, in the order their changes took effect. Drop an event older than the last sequence you saw for that person. Treat an id you have already handled as handled. Both rules apply to a webhook receiver too.

​
Thin, by default

An event carries ids, dates and the names of changed fields, never values. Read the record from the API when you need it: it is always current, and it respects the key’s groups. A webhook endpoint can switch on Include details to receive the record with the event. See Webhooks.