Webhook Integration Documentation

Authenticating Webhook Events

In order to authenticate that a webhook event was sent from Timeero and can be trusted, HTTP headers like the following examples are included on each request:

x-webhook-timestamp: 1617756644
x-webhook-signature: 197530c52c590212c3cbbfa......

To ensure the webhook event is authentic, verify the request using the provided x-webhook-timestamp and x-webhook-signature headers.

Headers

x-webhook-timestamp : The timestamp when the event was generated.
x-webhook-signature: The SHA-256 hash of the timestamp and payload.

Steps to Authenticate

Extract Headers: Retrieve x-webhook-timestamp and x-webhook-signature from the headers.
Compute Signature: Compute the SHA-256 hash of the x-webhook-timestamp concatenated with the request payload using your shared secret.
Compare Signatures: Compare the computed signature with the x-webhook-signature header. If they match, the request is authentic.

Example Code

Below is an example implementation in PHP for authenticating webhook events:

// Your shared secret
$sharedSecret = 'your_shared_secret';
// Extract headers
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_SIGNATURE'];
// Get the request body
$requestBody = file_get_contents('php://input');
// Compute the signature
$computedSignature = hash_hmac('sha256', $timestamp . $requestBody, $sharedSecret);
// Compare signatures
if (hash_equals($computedSignature, $signature)) {
    // Signature is valid
    echo 'Webhook event is authenticated.';
} else {
    // Signature is invalid
    echo 'Invalid signature.';
}
?>

Event Structure

Webhook events are sent as JSON payloads in the body of the POST request. Here is an example of a webhook event payload:

{
   "payload":{
      "event":"type",
      "data":{
         "id":46,
         "operation":"operation",
         "last_updated_at":1722519184
      }
   }
}

Groups

This section describes the structure of the event payloads for webhook events related to "Groups".

Event Payloads

groups_created

{
   "payload":{
      "event":"groups",
      "data":{
         "id":46,
         "operation":"groups_created",
         "last_updated_at":1722519184
      }
   }
}

groups_updated

{
   "payload":{
      "event":"groups",
      "data":{
         "id":46,
         "operation":"groups_updated",
         "last_updated_at":1722519184
      }
   }
}

groups_deleted

{
   "payload":{
      "event":"groups",
      "data":{
         "id":46,
         "operation":"groups_deleted",
         "last_updated_at":1722519184
      }
   }
}

Response Payload Description

payload: The main object containing the event data.
- event: The type of event. For groups, this will be "groups".
- data: An object containing the detailed data about the event.
  - id: The unique identifier for the group.
  - operation: The type of operation performed. It can be one of "groups_created", "groups_updated", or "groups_deleted".
  - last_updated_at: The Unix timestamp representing when the event occurred.

Users

This section describes the structure of the event payloads for webhook events related to "Users".

Event Payloads

users_created

{
   "payload":{
      "event":"users",
      "data":{
         "id":245,
         "operation":"users_created",
         "last_updated_at":1722519184
      }
   }
}

users_updated

{
   "payload":{
      "event":"users",
      "data":{
         "id":4126,
         "operation":"users_updated",
         "last_updated_at":1722519184
      }
   }
}

users_deleted

{
   "payload":{
      "event":"users",
      "data":{
         "id":4346,
         "operation":"users_deleted",
         "last_updated_at":1722519184
      }
   }
}

Response Payload Description

payload: The main object containing the event data.
- event: The type of event. For users, this will be "users".
- data: An object containing the detailed data about the event.
  - id: The unique identifier for the users.
  - operation: The type of operation performed. It can be one of "users_created", "users_updated", or "users_deleted".
  - last_updated_at: The Unix timestamp representing when the event occurred.

Jobs

This section describes the structure of the event payloads for webhook events related to "Jobs".

Event Payloads

jobs_created

{
   "payload":{
      "event":"jobs",
      "data":{
         "id":4936,
         "operation":"jobs_created",
         "last_updated_at":1722519184
      }
   }
}

jobs_updated

{
   "payload":{
      "event":"jobs",
      "data":{
         "id":43436,
         "operation":"jobs_updated",
         "last_updated_at":1722519184
      }
   }
}

jobs_deleted

{
   "payload":{
      "event":"Jobs",
      "data":{
         "id":426,
         "operation":"jobs_deleted",
         "lastUpdatedAt":1722519184
      }
   }
}

Response Payload Description

payload: The main object containing the event data.
- event: The type of event. For jobs, this will be "jobs".
- data: An object containing the detailed data about the event.
  - id: The unique identifier for the jobs.
  - operation: The type of operation performed. It can be one of "jobs_created", "jobs_updated", or "jobs_deleted".
  - last_updated_at: The Unix timestamp representing when the event occurred.

Tasks

This section describes the structure of the event payloads for webhook events related to "Tasks".

Event Payloads

tasks_created

{
   "payload":{
      "event":"tasks",
      "data":{
         "id":945,
         "operation":"tasks_created",
         "last_updated_at":1722519184
      }
   }
}

tasks_updated

{
   "payload":{
      "event":"tasks",
      "data":{
         "id":4324,
         "operation":"tasks_updated",
         "last_updated_at":1722519184
      }
   }
}

tasks_deleted

{
   "payload":{
      "event":"tasks",
      "data":{
         "id":324,
         "operation":"tasks_deleted",
         "last_updated_at":1722523014
      }
   }
}

Response Payload Description

payload: The main object containing the event data.
- event: The type of event. For tasks, this will be "tasks".
- data: An object containing the detailed data about the event.
  - id: The unique identifier for the tasks.
  - operation: The type of operation performed. It can be one of "tasks_created", "tasks_updated", or "tasks_deleted".
  - last_updated_at: The Unix timestamp representing when the event occurred.

Timesheets

This section describes the structure of the event payloads for webhook events related to "Timesheets".

Event Payloads

timesheets_created

{
   "payload":{
      "event":"timesheets",
      "data":{
         "id":496,
         "operation":"timesheets_created",
         "last_updated_at":1722519183
      }
   }
}

timesheets_updated

{
   "payload":{
      "event":"timesheets",
      "data":{
         "id":4637,
         "operation":"timesheets_updated",
         "last_updated_at":1722519384
      }
   }
}

timesheets_deleted

{
   "payload":{
      "event":"timesheets",
      "data":{
         "id":9467,
         "operation":"timesheets_deleted",
         "last_updated_at":1722522014
      }
   }
}

Response Payload Description

payload: The main object containing the event data.
- event: The type of event. For timesheets, this will be "timesheets".
- data: An object containing the detailed data about the event.
  - id: The unique identifier for the timesheets.
  - operation: The type of operation performed. It can be one of "timesheets_created", "timesheets_updated", or "timesheets_deleted".
  - last_updated_at: The Unix timestamp representing when the event occurred.

Schedules

This section describes the structure of the event payloads for webhook events related to "Schedules".

Event Payloads

schedules_created

{
   "payload":{
      "event":"schedules",
      "data":{
         "id":246,
         "operation":"schedules_created",
         "last_updated_at":1722519184
      }
   }
}

schedules_updated

{
   "payload":{
      "event":"schedules",
      "data":{
         "id":4369,
         "operation":"schedules_updated",
         "last_updated_at":1722519184
      }
   }
}

schedules_deleted

{
   "payload":{
      "event":"schedules",
      "data":{
         "id":4683,
         "operation":"schedules_deleted",
         "last_updated_at":1722523014
      }
   }
}

Response Payload Description

payload: The main object containing the event data.
- event: The type of event. For schedules, this will be "schedules".
- data: An object containing the detailed data about the event.
  - id: The unique identifier for the schedules.
  - operation: The type of operation performed. It can be one of "schedules_created", "schedules_updated", or "schedules_deleted".
  - last_updated_at: The Unix timestamp representing when the event occurred.