HTTP synchronization of absences (webhook)

Before starting

This article concerns the so-called "HTTP" synchronization, which is a webhook for sending absences from Timmi Absences to an external tool. It can be used if we do not provide a dedicated connector (we currently offer integrations with Google Calendar, Office365/Exchange and ADP GXP).

Synchronized events

You can choose the events that will be sent by the web service:

• all events (absences created pending validation, validated absences, deleted absences)
• only validated events (validated absences, deleted absences)

Status of requests

This diagram describes the different possible status of requests, depending on the actions performed in Timmi Absences.

Format of the message sent

Each time it is created, the message will be sent as follows:

• Verb: POST
• URL: you must provide the URL to be called whenever an absence is created or deleted
• Header :
  - Authorization
  - X-Version
  - X-Resource-Type
  - X-Event
• Body : payload in json

Header

The header contains the following fields:

• Authorization, which contains the authorization key you provide.
  Example: Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
  
  
• X-Version: payload format version (provided by Timmi Absences)
• X-Resource-Type: type of object sent (leave only in current version)
• X-Event: event having generated the call (created, approved, deleted)

Payload format

Absences are sent in half-days, called leave. For an absence of 2 days, there will therefore be 4 calls, each containing a payload of one leave.

Special case for absences in hours: a field is added (see the description below).

Payload example

{
"id": "78287-20180424-PM",
"date": "2018-04-24",
"isAm": false,
"owner": {
"id": 134,
"name": "Luca Pacioli",
"email": "luca.paccioli@lucca.fr",
"employeeNumber": "00001"
},
"leaveAccount": {
"id": 1718,
"name": "Congés payés 2018",
"categoryId": 1,
"categoryName": "Congés payés"
},
"isConfirmed": true,
"confirmationDate": "2018-04-04T22:34:47.797",
"isCancelled": false,
"cancellationDate": ""
}

Payload description

• id: unique ID of the leave

• date: date of the leave

• isAM: half-day (AM: true, PM: false)

• leaveAccount: leave account

  • id: account ID in Timmi Absences
  • name: account name
  • categoryId: ID of the account category, in the event of old accounts
  • categoryName: name of the account category, in the case of old accounts

• durationInHours: duration in hours, if counted in hours only (e.g. "03:45:00")

• isConfirmed: absence validation status

• creationDate: creation date

• isCancelled: cancellation status

• cancellationDate: cancellation date

If you need to recover a list of items to create a correspondence table in your target platform, please refer to our API documentation where you will also find the information available in your Timmi Absences interface (absences, accounts, account categories, etc).

Return format

Timmi Absences does not expect a specific return when sending the payload linked to an event. The response is not analyzed, only the return message is used for display in the detail of events on the tracking interface.

Tracking interface

Events that have been sent can be tracked through the synchronization web service interface in Timmi Absences.

For each event, you can view the details of the message sent, and in the event of an error, re-sync the event manually, or mark it as processed. In this case, it will no longer be considered an error.

Synchronization errors are reported to the administrator's pending tasks dashboard.

Please note: only errors returned when the payload is received are processed. If you perform asynchronous business processing, we cannot recover any errors you may encounter.

Re-sync policy

If the call fails, the event is sent to a queue for re-syncing. There are 4 cascading queues, 5 minutes, 15 minutes, 1 hour, 24 hours.