Leave webhook (HTTP Synchronisation)

Background information

This article focuses on HTTP synchronisation, which is a webhook provided by Timmi Absences to send absences to a third-party tool if we do not offer a dedicated connector (see the list of available connectors).

Synced events

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

• all events (absences created and pending approval, approved absences, deleted absences)
• approved events only (approved absences, deleted absences)

Format of the sent message

The message will be sent as follows:

• Verb: POST
• URI: you must provide the URL that will be called each time an absence is created or deleted
• Header:
  • Authorization
  • X-Version
  • X-Resource-Type
  • X-Event
• Body: the payload

Header breakdown

The header contains the following fields:

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

Payload format

Absences are sent by half-day, called leaves. So for a 2-day absence, the payload will contain 4 leaves.

Absences in hours will have an additionnal value, see below.

Example payload

{
"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": "Annual leave 2018",
"categoryId": 1,
"categoryName": "Annual leave"
},
"isConfirmed": true,
"confirmationDate": "2018-04-04T22:34:47.797",
"isCancelled": false,
"cancellationDate": ""
}

Details of payload values

• id: unique identifier for the leave

• date: date of the leave

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

• leaveAccount: absence account

  • id: the account’s identifier in Timmi Absences
  • name: the account’s name
  • categoryId: the account category’s identifier, for yearly accounts
  • categoryName: the account category’s name, for yearly accounts

• durationInHours: duration in hours (only if the account is in hours)

• isConfirmed: the absence’s approved status

• creationDate: date of creation

• isCancelled: cancelled status

• cancellationDate: date of cancellation

Statuses of requests

This diagram shows the different possible request statuses based on actions taken in Timmi Absences.

Follow-up interface

Events sent can be tracked in the synchronisation web service interface in Timmi Absences.

For each event, you can see the details of the message sent and, if there is an error, re-sync the event manually or mark it as processed. In this case, it is no longer considered an error.

Synchronisation errors are reported on the dashboard of the administrator’s to-do list.

Re-syncing policy

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