HTTP synchronization of absences (webhook)

Before you get started

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 configure 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)

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 call each time an absence is created or deleted
• Header:
  - Authorization
  - X-Version
  - X-Resource-Type
  - X-Event
• Body: the JSON payload

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

Payload description

• id: unique identifier of the leave

• date: leave date

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

• leaveAccount: leave account

  • id: account identifier in Timmi Absences
  • name: account name
  • categoryId: identifier 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

Status of requests

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

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.