TruLinks
TruTac

Webhooks

Webhooks allow you to build or set up Apps which subscribe to certain events from the TruTac range of products. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to update external systems, be alerted to changes, or even just to store a mirror of the data. You're only limited by your imagination.

Webhooks are installed at a organization level. Once installed, the webhook will be triggered each time one or more subscribed events occurs.

Events

When configuring a webhook, you can choose which events you would like to receive payloads for. You can even opt-in to all current and future events. Only subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server. You can change the list of subscribed events through the UI anytime.

Each event corresponds to a certain set of actions that can happen to your organization. For example, if you subscribe to the clocking event you'll receive detailed payloads every time a user clocks in or out, or an existing clocking is changed.

The available events are:

Name Description
* Any time any event is triggered (Wildcard Event).
clocking Any time a Clocking is created, edited, deleted.
checksheet Any time a Checksheet is created, edited, deleted.

Wildcard Event

We also support a wildcard (*) that will match all supported events. When you add the wildcard event, we'll replace any existing events you have configured with the wildcard event and send you payloads for all supported events. You'll also automatically get any new events we might add in the future.

Payloads

Each event type has a specific payload format with the relevant event information. All event payloads mirror the payloads for the Event types.

Note: Payloads are capped at 5 MB. If your event generates a larger payload, a webhook will not be fired. We suggest monitoring your payload size to ensure delivery.

Delivery headers

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:

Header Description
TT-Hook-Event Name of the event type that triggered the delivery.
TT-Hook-Signature The HMAC hex digest of the response body. This header will be sent if the webhook is configured with a secret. The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key.

Example delivery

POST /payload HTTP/1.1
Host: localhost:4567
TT-Hook-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6
Content-Type: application/json
Content-Length: 6615
TT-Hook-Event: clocking
{
  "action": "created",
  "clocking": {
       "id": "CLOCKING-ID-123",
       "driverId": "DRIVER-ID-123",
       "clockingTimeStamp": "2018-01-01T09:01:53",
       "isClockIn": true
   }
}

Ping Event

When you create a new webhook, we'll send you a simple ping event to let you know you've set up the webhook correctly.

Ping Event Payload

Key Value
webhookId The ID of the webhook that triggered the ping
hook The webhook configuration