Introduction

The TrackTik API and its cloud driven back end were designed so you can retrieve information yourself as a developed integration solution, modify existing data, or create new data. But it can also POST/call-out data to a third-party system as part of a real-time triggers and actions based integration. The service that permits this is called: Events Subscriptions.

An Events Subscription is a call-out service that you create and configure yourself. A standard configuration usually consists of the following parts:

1. Data entity/endpoint - REQUIRED
2. Trigger (create, update, API action) - REQUIRED
3. Filter (like =, :not, :in parameters of API GET calls) - OPTIONAL
4. Inclusions list (relation lists, on demand fields) - OPTIONAL
5. Regional context (all regions or portion of a regional tree) - REQUIRED
6. Webhook access and authorization (URL, secret header name, secret, error notification email address) - REQUIRED

Basic Configuration

The most basic of configurations will be the below, which is an example of a subscription that sends information about new employees to a third-party system, say an HR system, when they are created:

[POST] /events-subscriptions

{ "customId" : "customId of your choosing like ABC-123", "name" : "A bit more descriptive text about the purpouse of this subscription", "events" : [ "entity:employees:created" ], "contextFilters": { "filters": [ { "tag": "context.region.3", "includeChildren": true } ] }, "url" : "https://your.webhook.url/path/path", "secretHeaderName" : "TrackTik-subscription-secret-without-spaces", "secret" : "B2C60113ECB7 etc.", "failureEmail" : "(optional) An email address you'd like to monitor errors at" }

This subscription will work like this:

1. For data entity "employees"
2. Triggered by event "created"
3. And only for employees that belong to any region in the tree who's top node has id of 3
4. Obtain the same JSON response as when one does a [GET] /employees
5. And send hat JSON response to url https://your.webhook.url/path/path
6. With authentication header parameters of secretHeaderName, and secret
7. And should any errors occur, communicate this error to email address failureEmail
8. The language parameter isn't being defined, so it will default to EN-US

Features

In addition to being able to define the when and what of a call-out, you'll also be able to work with the /events-subscriptions endpoint to view status, logs and more. 

For more information see our more detailed technical documentation.