Event-driven data from Personio

Webhooks have been introduced in API version 2.0 to enhance efficiency by reducing the need for repeated polling for updates. This not only conserves your resources but ours as well. Where webhooks are available, API requests will have set rate limits and repetitive polling will not be permitted.

🚧

If you need additional webhooks that are crucial for your integration but currently unavailable, please reach out to your Partnerships TPM to submit a request. We assess all requests based on their potential value to our API ecosystem.

Utilize the webhooks management API to arrange for the necessary webhook events callbacks.

Person & Employment Events (Employees)

Person.created: When a new person entity is added

Person.updated : When there are updates to a person’s attribute. Note that not all attribute changes will trigger this event, but all custom attributes will. For more details, refer to the documentation

Person.deleted: When a person's entity is deleted

Employment.created: When a new employment for an employee is added

Employment.updated: When an employment for an employee is changed. Check in the documentation the attribute changes that trigger this event.

Employment.deleted: When an employment is removed from the system, or the associated Person is deleted.

Use Person Events to be notified when this attribute changes and respond by creating a profile and fetching any necessary data from other API endpoints. See the next page for the suggested handling logic.

Employee Leave

Leaves represent long-term absence periods, for example parental leave. Leave periods are created and managed in Personio, and are technically different from absences. However, the Absence API will return scheduled leaves for an employee as long as the leave is associated with an Absence Type when it is created. These periods are read-only in the API.

HRMs create the leaves in Personio and associate them to the appropriate absence types. You’ll receive creation, deletion and update webhooks in the same event as absences. Partners should always listen for changes on such webhooks.

No separating handling of Leaves is needed; instead, customers should ensure that leaves are associated with an Absence Type on creation - the integration approach defined in Absences can then be used.

You should evaluate if, in the case of an employee on leave, you will continue billing the customer for the employee or not.

See the next page for the suggested handling logic.

Employee terminations and deletions

Terminations and profile deletions are also signaled via Employment event webhooks.

When an employee is terminated they are not removed from the Personio system but should be removed from the partner system to avoid unnecessary billing. Depending on the customer, termination can be signalled by updating the termination date attribute of the active Employment object (listen to employment.updated), or by setting the person’s status to Inactive (listen to person.updated). Additionally, employee profiles may also be deleted entirely from the Personio system (listen to person.deleted event).

See the next page for the suggested handling logic.