Webhooks

Collections

Clockings

Webhooks

Introduction

It’s possible to retrieve change-events of clockings with webhooks.

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

POST

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/webhooks

Body properties

This list of properties is applicable for this endpoint.

Property	Type	Description
`destinationUrl`	string	The URL where webhook notifications will be sent.
`collectionName`	string	The name of the collection to subscribe to (`clockings`).

Event properties

This list of properties is posted to your consumer endpoint.

Property	Type	Description
`changeVersion`	string	Property to indicate the order of changes.
`id`	integer	Unique identifier for the clocking.
`person.id`	integer	Internal ID of the person who performed the clocking.
`date`	string	Date of the clocking (YYYY-MM-DD).
`timeOfDayInMinutes`	integer	Minutes since midnight (-1440 and 2880) representing the time of the clocking on the specified date.
`originalTimeOfDayInMinutes`	integer	Original time of the clocking as registered by the terminal or input source. Only present if the clocking has been edited.
`calculatedTimeOfDayInMinutes`	integer	The time of day in minutes after any corrections or calculations.
`isGenerated`	boolean	Indicates if the clocking was generated by the system.
`terminal.id`	integer	Internal ID of the terminal on which the clocking occurred.
`geolocation.longitude`	number	Longitude coordinate where the clocking was registered.
`geolocation.latitude`	number	Latitude coordinate where the clocking was registered.
`kind`	string	Type of clocking (`InOut`, `Reason`, `Activity`, `ActivityEnd`).
`reason.id`	integer	Internal ID of the reason for the clocking (only present if `kind` is `Reason`).
`activityLevels`	array	Array of activity levels, each with a `level` and an `activityDefinition.id` (only present if `kind` is `Activity`).
`status`	string	Status of the clocking (`Unknown`, `Active`, `Deleted`).

External references

It’s possible to use predefined external references and custom external references. More information can be found on the External References Page

For a list of predefined external references, see the external reference options section.

Note

Check the query options below the endpoint on the Swagger page for the relevant external references.

Good to know

Overnight clockings

The Protime API supports handling overnight clockings. Clocking data is imported on the correct day, based on the configuration of the schedule within Protime.

In most cases, clockings are created with normal time values (0–1439 minutes since midnight), and the schedule configuration determines on which day the clocking appears. For example, a check-in at 22:00 (timeOfDayInMinutes: 1320) on 13 February might be assigned to 14 February if the day schedule is configured that way for night shifts.

In webhook events, you may see timeOfDayInMinutes values in the extended range from -1440 to 2880 when a clocking has been explicitly placed on a previous or next day. Refer to the Create a clocking page for a detailed explanation of both scenarios.

Soft-deleted clockings

Note

Soft-deleted clockings are included in the responses. These are clockings that have been manually deleted but remain in the system with a “Deleted” status.

In events, soft-deleted records appear as:

"changeType": "InsertOrUpdate" indicating whether the record was added or updated (InsertOrUpdate) or physically deleted (Delete).
"status": "Deleted" indicating whether a clocking is active or soft-deleted.

Example of a soft-delete in a delta response:

{
  "changeType": "InsertOrUpdate",
  "data": {
    "status": "Deleted",
    "timeOfDayInMinutes": 9999,
    "originalTimeOfDayInMinutes": 551,
    "date": "2025-04-22",
    "kind": "InOut",
    "terminal": {
        "id": 684743
    },
    //...
  }
}

Example

A webhook for clockings

Example for creating a webhook for clockings:

POST

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/webhooks

{
    "destinationUrl": "https://www.fictional-customer.com/protime/clockings",
    "collectionName": "clockings"
}

Retrieve a delta