Webhooks
Subscribes to change events for one historical field category.
Caution
Read the Webhooks page. There is important information on required implementation!
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/webhooks
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-webhooks.write and connector-protimeapi-people-historical-data.read
Note
connector-protimeapi-people.read does not satisfy the read requirement for the historical field categories, even though the historical field list endpoints accept it.
Body properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
destinationUrl |
string | Yes | Yes | The URL where webhook events will be sent. |
collectionName |
string | Yes | Yes | The name of the collection to subscribe to (see the categories table below). |
Historical field categories
Each category is a separate collection. A webhook subscribes to one category.
| Category | collectionName |
Event field name |
|---|---|---|
| departments | department-histories |
department.id |
| employers | employer-histories |
employer.id |
| jobs | job-histories |
job.id |
| job categories | job-category-histories |
jobCategory.id |
| sectors | sector-histories |
sector.id |
| work locations | work-location-histories |
workLocation.id |
Event properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
id |
integer | — | Read-only | Internal unique identifier for the historical field record. |
changeVersion |
string | — | Read-only | Property to indicate the order of changes. |
person.id |
integer | — | Read-only | Internal unique identifier for the person. |
until |
string | — | Read-only | End date of the historical field record (YYYY-MM-DD). Not returned while the record is still active. |
<category>.id |
integer | — | Read-only | Internal unique identifier for the related entity. The field name depends on the category (see table above). |
from |
string | — | Read-only | Start date of the historical field record (YYYY-MM-DD). |
Department history events list their properties in the order person, id, changeVersion, until, from, department.
External references
The endpoint supports predefined and custom external references. See the external references page for details and the predefined options list.
Each history type supports the people collection and its own entity collection:
| History type | Supported collections | Predefined | Custom |
|---|---|---|---|
department-histories |
people, departments |
@badge-number, @employee-number (people only) |
Supported |
employer-histories |
people, employers |
@badge-number, @employee-number (people only) |
Supported |
job-histories |
people, jobs |
@badge-number, @employee-number (people only) |
Supported |
job-category-histories |
people, job-categories |
@badge-number, @employee-number (people only) |
Supported |
sector-histories |
people, sectors |
@badge-number, @employee-number (people only) |
Supported |
work-location-histories |
people, work-locations |
@badge-number, @employee-number (people only) |
Supported |
Error responses
| Status | Condition |
|---|---|
400 |
Invalid destination URL, unknown collection name, or invalid external reference |
401 |
Missing or invalid access token, or insufficient scope |
Success response
201 Created with webhookKey and validUntil in the response body.
Examples
Creating a webhook for department histories
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/webhooks
{
"destinationUrl": "https://www.fictional-customer.com/protime/department-histories",
"collectionName": "department-histories"
}Creating a webhook for employer histories with an external reference
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/webhooks?externalReferences=(people,@employee-number)
{
"destinationUrl": "https://www.fictional-customer.com/protime/employer-histories",
"collectionName": "employer-histories"
}