Event handling/handler

Event handling offers you the option of triggering predefined actions for certain events. Predefined action types such as SMS or email can be used for simple signals. For more complex actions, Tripshare also offers webhooks, i.e. a URL is called up on the Internet and the event data is transferred via POST.

Create handler

To do this, click on the symbol in the handler overview

Standard fields

Each handler has two standard fields for Name and Description.

Give your handlers a name and a description so that they can be clearly identified in the overview list.

Device list

Handlers are assigned to their devices. You can select one or more devices that serve as a source for events.

To do this, scroll through the list of your devices; you can also enter a filter text as shown in the example so that only devices containing the text are displayed. If you only have a few devices, it is usually not necessary to use filters.

Event code

Use the event code to specify the events that trigger the action. The list contains the event codes of the Tripshare platform.

You can select various codes from the list or the entry - all -, which selects all events.

Info

The event code POSITION is only evaluated for the handler type Webhook. Actions such as email, SMS or Telegram can otherwise block the call of the hook at very short time intervals, as quotas are reached very quickly. The WEBHOOK type may only be available at a higher rate! Please contact support@protegear.com

Handler type

Depending on the type of handler, you can enter different data

EMail

You can generate the subject and content of the email using templates. Please note that automatically generated emails can often get stuck in SPAM filters.

You can use the following template to send an email with all data for debugging purposes:

{{ emoji .Event.Code}}: this is my tripsharehandler.
The device "{{.Device.Name}}" sent {{.Event.Code}}: {{.Event.IMEI}}

All:
Event: {{ printf "%+v" .Event }}
Device: {{ printf "%+v" .Device }}

JSON:
Event: {{ marshal .Event }}
Device: {{ marshal .Device }}

SMS

Info

SMS messages are subject to a charge

If the content of an SMS is generated dynamically, it is essential to ensure that the content is short, as otherwise long texts are sent with the help of individual SMS’s and these are each subject to a charge.

Telegram

Telegram supports a subset of HTML tags that you can use. It is recommended to use as little formatting as possible, as unsupported tags/formats will cause Telegram to reject these messages.

You can obtain the ChatId by adding our ChatBot with the name @ProtegearBot to your desired chat in the Telegram app on your smartphone. If you do not yet have a chat, click on the link above to create a chat. If the bot is a member of the chat, you can use the command /chatid to request the ID of the chat. The bot will display this and you can enter this ID in the field provided.

Info

If you have an existing chat that you want to use as a channel, please add @ProtegearBot as a member. A click on the link creates a new chat instead or selects an existing chat between you and the bot.

Slack

In addition to the message, which you can generate dynamically, you must also enter the URL of your webhook for Slack support. To find out how to create such a webhook in Slack, please refer to the description at Slack.

Webhook

A webhook is a URL that terminates on the Internet at a server of your choice. You can enter any URL you want here. However, to ensure a certain level of security, the following options are available:

• Enter a URL that contains special parameters that only you know and that you check on your server
• Enter values in the ‘Headers’ field that our system then sends to your server as HTTP headers. In contrast to URL parameters, header parameters are not normally visible in logs
• Use an HMAC with a secret key. You can then use a few lines of code to check whether the incoming request was sent by Protegear.

If your server has an insecure certificate (selfsigned), please activate the Skip TLS Check switch.

Warning

Switching off the TLS check is only recommended for testing/development. The check should always be activated in productive systems.

Events are passed to the webhook. In contrast to the other handlers, there are no templates or similar here. Instead, the hook is called for incoming events. However, it is not guaranteed that a webhook always contains exactly one event. If there are many events, the system can also send them as a batch. ##### Test webhook

You can use the ‘Send Test Message’ button to test the webhook with a dummy event at any time.

Alternatively, you can also send real data to your system. To do this, select a start and end date. Tripshare will then select the events from this period and send them to your webhook. You can use ‘Count Events’ to count in advance how many events in our database match the criterion and only then send the data using ‘Push Events’. Use the batch limit to define the maximum number of events to be transported per request.

Handler content

You can define the data to be transferred for each handler. To do this, you can design the content of the message dynamically using Go Templates.

Each template receives the data of the event and the device in the fields .Event and .Device. As the template language of go is used, you must know these field names to access the fields.

The data structure for Device is as follows:

type Device struct {
    ID                string              `json:"id"`
    SecondaryID       string              `json:"secondary_id"`
    Name              string              `json:"name"`
    Changed           time.Time           `json:"changed"`
    ChangedBy         string              `json:"changedBy"`
    Type              DeviceType          `json:"type"`
    Organization      string              `json:"organization"`
    Comment           string              `json:"comment"`
    ContractID        string              `json:"contractid"`
    Rate              DeviceRate          `json:"rate"`
    Firmware          string              `json:"firmware"`
    Configuration     DeviceConfiguration `json:"configuration"`
    Status            DeviceStatus        `json:"status"`
    EventLifetimeDays int                 `json:"eventLifetimeDays"`
}
type DeviceConfiguration struct {
    Activation      ActivationType `json:"activation"`
    GSM             bool           `json:"gsm"`
    Satellite       bool           `json:"satellite"`
    RescueService   bool           `json:"rescueService"`
    RescueType      RescueType     `json:"rescueType"`
    ReceiveMessages bool           `json:"receiveMessages"`
}
type DeviceRate struct {
    Active   string `json:"active"`
    Inactive string `json:"inactive"`
}
type DeviceStatus string
type ActivationType string
type RescueType string

Ein Event hat folgende Struktur:

type Event struct {
    IMEI        string           `json:"imei"`
    Sent        time.Time        `json:"sent"`
    Received    time.Time        `json:"received"`
    Code        EventCode        `json:"code"`
    DeviceCode  int              `json:"deviceCode,omitempty"`
    DeviceEvent string           `json:"deviceEvent"`
    Text        string           `json:"text,omitempty"`
    Position    *PositionInfo    `json:"position,omitempty"`
    Addresses   []string         `json:"addresses,omitempty"`
    Battery     *BatteryInfo     `json:"battery,omitempty"`
    Info        *EventInfo       `json:"info,omitempty"`
    State       *DeviceInfo      `json:"state,omitempty"`
    Crash       *CrashInfo       `json:"crash,omitempty"`
    Environment *EnvironmentData `json:"environment,omitempty"`
    Type        string           `json:"type,omitempty"`
    Source      EventChannel     `json:"source,omitempty"`
}
type PositionInfo struct {
    Invalid         bool        `json:"invalid"`
    Latitude        float64     `json:"lat"`
    Longitude       float64     `json:"lng"`
    Altitude        int         `json:"alt"`
    Height          int         `json:"height"`
    Gpsfix          int         `json:"gpsfix"`
    NumSatellites   int         `json:"numsatellites"`
    Course          int         `json:"course"`
    SpeedKmH        float64     `json:"speedkmh"`
    VerticalSpeedMs float64     `json:"verticalspeedms"`
    MotionlessSec   int         `json:"motionless"`
    HDOP            float64     `json:"hdop"`
    VDOP            float64     `json:"vdop"`
    Pos6D           *Position6D `json:"pos6d,omitempty"`
}
type BatteryInfo struct {
    LoadInPercent int     `json:"loadpercent"`
    Low           bool    `json:"low"`
    LoadVoltage   float64 `json:"loadvoltage"`
}
type EventInfo struct {
    Intervall int `json:"intervall"`
}
type DeviceInfo struct {
    SOS InfoState `json:"sos"`
}
type CrashVector struct {
    X float64 `json:"x"`
    Y float64 `json:"y"`
    Z float64 `json:"z"`
}

type CrashInfo struct {
    Acceleration []CrashVector `json:"acceleration"`
}
type EnvironmentData struct {
    Temperature *int `json:"temperature,omitempty"`
    AirPressure *int `json:"airpressure,omitempty"`
}
type Position6D string
type EventChannel string
type EventCode string