Your browser is not up to date. This may cause security, speed, and display
issues. Please update your browser.
Update Browser
X
Clockodo API:
Webhooks
Webhooks allow you to react to events in Clockodo in real time. When a defined event occurs, our system automatically sends an HTTP POST request to an URL you specify. This enables you to trigger your own workflows or automate and synchronize external systems.
New API documentation
Feel free to use our updated API documentation.
Supported Webhook Events
| Entity | Event Types | |
|---|---|---|
| User |
• user.created • user.updated • user.deleted | |
| Absence |
• absence.created • absence.updated • absence.deleted • absence.approved | |
| Customer |
• customer.created • customer.updated • customer.deleted | |
| Project |
• project.created • project.updated • project.deleted • project.completed | |
| Subproject |
• subproject.created • subproject.updated • subproject.deleted | |
| Service |
• service.created • service.updated • service.deleted | |
| Team |
• team.created • team.updated • team.deleted | |
| Lump Sum Service |
• lump_sum_service.created • lump_sum_service.updated • lump_sum_service.deleted | |
| Holidays Carry |
• holidays_carry.created • holidays_carry.updated • holidays_carry.deleted | |
| Holidays Quota |
• holidays_quota.created • holidays_quota.updated • holidays_quota.deleted | |
| Overtime Carry |
• overtime_carry.created • overtime_carry.updated • overtime_carry.deleted | |
| Nonbusiness Group |
• nonbusiness_group.created • nonbusiness_group.updated • nonbusiness_group.deleted | |
| Work Time Change Request |
• work_time_change_request.created • work_time_change_request.updated • work_time_change_request.deleted | |
| Entry |
• entry.created • entry.updated • entry.deleted • entry.started • entry.stopped |
Creating and Editing a Webhook
Creating/editing a Webhook
You can create a new webhook or edit an existing one via the Webhooks section in the menu. Simply select the desired event (see table above), then enter the target URL and a token.
Webhook Validation
When setting up a webhook for the first time or changing its URL, it must be validated. This step ensures security and confirms that you control the specified target URL.
To validate the webhook, Clockodo sends a POST request to the URL you provided, including the following payload:
{
"secret": "8ee3d438-fbfc-411c-a38a-25893becd505"
}Enter the received secret into the corresponding input field in Clockodo.
Webhook-Payload
Each webhook call is sent as an HTTP POST request in JSON format to the configured URL. The general structure is as follows:
{
"subscription_id": 42,
"company_id": 1337,
"occurred_at": "1986-05-10T17:02:00Z",
"payload": {
"team": {
"id": 9001
}
},
"event_name": "team.updated",
"token": "My_Sup3r_T0k3n"
}- subscription_id
Unique ID of the webhook subscription - company_id
ID of your company in Clockodo - occurred_at
Timestamp of the event (ISO 8601, UTC) - event_name
Type of the triggered event - payload
Contains the affected entity and its ID - token
The token you defined when setting up the webhook (used to authenticate incoming requests)
We only transmit the ID of the created, modified, or deleted entity. We don't transmit full datasets or deltas.
This approach offers several advantages:
- Data Security
No sensitive or extensive data is transmitted unnecessarily. - Data Freshness
After receiving a webhook event, you can retrieve the current and complete data via API. This helps to prevent inconsistencies caused by parallel changes or delays. - Reduced Risk of Errors
For complex or rapidly changing data structures, querying the current state is often more reliable than processing potentially outdated snapshots. - Flexibility
Your system can decide when and to what extent it needs additional information.
Best Practices and Recommendations
- Event Validation
Always verify the token and structure of incoming webhook data. - Idempotency
Ensure your systems can correctly handle duplicate or repeated events. - Logging
Log incoming webhook calls for debugging and traceability purposes.