Webhooks

Get Notified

Enable webhooks for you application and we will send a notification when something interesting occurs for your users. This can greatly your simplify the overhead for loading data, since polling the restful APIs may no longer be necessary.

Configuration is simple:

  1. Login to the ZINC developer portal.
  2. Select the application you wish to change and check “enable webhooks.”
  3. Enter your secure server side URL endpoint and specify the types of events you wish to receive.   (ex: https://myapp.mycompany.com/zubie)

That’s it! Now when an event occurs for your any of your connected users Zubie will POST JSON event payloads to your endpoint in real time. Each payload will include a unique event ID and a USER_ID, to identify the user that triggered the event.

 

Event Types

Trips

  • Place Arrival
  • Place Departure
  • Trip Start
  • Trip End

Vehicle Health

  • Trouble Code
  • Low Battery
  • Low Fuel
  • Maintenance Reminder

Driving

  • Severe Hard Braking
  • Hard Brake
  • Over Speeding
  • Rapid Accelerations

Device

  • Device Unplugged
  • New Device Activated
  • Device Moved to New Vehicle

Sample Payloads

Trip Start

{
    "trip": {
        "event": "trip_start",
        "key": "agpzfnp1YmllY2FyckILEgZEZXZpY2UiFjRFWFBZbVdGQW8",
        "started_timestamp": "2015-08-07T00:25:59-04:00",
        "started_address": {
            "city": "Sullivan's Island",
            "state": "SC",
            "street": "402 Station 18 1/2 St"
        },
        "distance": 0,
        "idle_time": 0,
        "fuel_cost": 0,
        "rapid_accels": 0,
        "hard_brakes": 0,
        "fuel_cost_currency_code": "USD",
        "ended_timestamp": null,
        "ended_address": null,
        "max_speed": null,
        "id": "ShNLREXjuu6yFMdpX5zi64"
    },
    "timestamp": "2015-08-07T00:25:59-04:00",
    "timestamp_offset": -240,
    "user_id": "FCBwEuAu8A4gLJtrWdpYKI3s",
    "car": {
        "battery_level": 12.4,
        "vin": "5FNRL38249B044393",
        "key": "agpzfnp1YmllY2FycjcLEgdBY2NvdW50IhZnRjgydXNpT",
        "fuel_level": 80,
        "nickname": "Test",
        "id": "AYFJdiAD2bJ"
    }
}

Trip End

{
    {
        "event": "trip_end",
        "timestamp": "2015-08-07T00:25:59-04:00",
        "user_id": "FCBwEuAu8A4gLJtrWdpYKI3s",
        "trip": {
            "key": "agpzfnp1YmllY2FyckILEgZEZXZpY2UiFjRFWFBZbVdGQW8",
            "id": "ShNLREXjuu6yFMdpX5zi64",
            "distance": 2.1,
            "ended_timestamp": "2015-08-07T00:25:59-04:00",
            "idle_time": 120,
            "fuel_cost": .25,
            "rapid_accels": 1,
            "hard_brakes": 0,
            "fuel_cost_currency_code": "USD",
            "ended_address": {
                "city": "Sullivans Island",
                "state": "SC",
                "street": "1000 Central Avenue"
            },
            "max_speed": 41.63186987990137,
            "started_timestamp": "2015-08-07T00:25:59-04:00",
            "started_address": {
                "city": "Sullivans Island",
                "state": "SC",
                "street": "2000 Central Avenue"
            },
        },
        "car": {
            "vin": "5FNRL38249B044393",
            "key": "agpzfnp1YmllY2FycjcLEgdBY2NvdW50IhZnRjgydXNpT",
            "fuel_level": 5,
            "nickname": "Truck",
            "id": "AYFJdiAD2bJ"
        }
    }

Low Fuel

{
    "event": "vehicle_fuel_low",
    "timestamp": "2015-08-07T00:25:59-04:00",
    "user_id": "FCBwEuAu8A4gLJtrWdpYKI3s",
    "car": {
        "vin": "5FNRL38249B044393",
        "key": "agpzfnp1YmllY2FycjcLEgdBY2NvdW50IhZnRjgydXNpT",
        "fuel_level": 5,
        "nickname": "Truck",
        "id": "AYFJdiAD2bJ"
    }
}

Trouble Code

{
"event": "vehicle_trouble_code",
"timestamp": "2015-08-07T00:25:59-04:00",
"user_id": "FCBwEuAu8A4gLJtrWdpYKI3s",

"trouble_code": {
"code": "P0635",
"description": "Power Steering Control Circuit",
"repair_cost_low": 500,
"repair_cost_high": 1000,
"detailed_description": "This fault code indicates the Comprehensive Component Monitor (CCM) has detected that the Intake Air Temperature (IAT) sensor 1 signal was higher than the maximum expected value for a predetermined period of time for the driving conditions present when the code was set.",
"severity": 2
},

"car": {
"vin": "5FNRL38249B044393",
"key": "agpzfnp1YmllY2FycjcLEgdBY2NvdW50IhZnRjgydXNpT",
"fuel_level": 5,
"nickname": "Truck",
"id": "AYFJdiAD2bJ"
}

}

Place Departure

{
    "event": "vehicle_geofence_departure",
    "timestamp": "2015-08-07T00:25:59-04:00",
    "user_id": "FCBwEuAu8A4gLJtrWdpYKI3s",
    "geofence": {
        "id": "UyLbXzbgAGf",
        "radius": 0.1,
        "name": "1560BenSawyerBlvd",
        "key": "agpzfnp1YmllY2FycjwLEgdBY2NvdW50IhZnRjgydXNpT",
        "address": "1560 Ben Sawyer Blvd, MtPleasant, SC29464"
    },
    "car": {
        "vin": "5FNRL38249B044393",
        "key": "agpzfnp1YmllY2FycjcLEgdBY2NvdW50IhZnRjgydXNpT",
        "fuel_level": 5,
        "nickname": "Truck",
        "id": "AYFJdiAD2bJ"
    }
}

Hard Brake

{
event: 'trip_hard_brake',
timestamp: '2015-12-03T01:06:59-03:00',
car: {
battery_level: 12.4,
fuel_level: 80,
id: '7KnEgEThRfv',
key: 'agpzfnp1YmllLXFhcjcLEgdBY',
nickname: '2014 Ford F-150',
vin: '1FTFW1ET6EFB98542'
},
point: {
acceleration: -7.1,
heading: 186,
id: 1449104819,
key: 'agpzfnp1YmllLXFhcjULEgZEZ',
latitude: 40.856,
longitude': -73.82513166666666,
speed: 20.50524934383202,
speed_by_second: [],
timestamp: '2015-12-03T01:06:59-03:00'
},
trip: {
id: 'tHkESZBLgSx3Nyu4ypxFHF',
key: 'agpzfnp1YmllLXFhckILEgZEZXZpY2UiFl',
max_speed: 25.47621888173069,
started_address: {
city: 'New York',
state: 'NY',
street: '2199 Bolton St'
},
started_timestamp: '2015-12-03T01:00:00-05:00'
}
},
id: 'EqAp8Sk6pS4HQvpuVmt7g6',
kind: 'TripHardBrakeEvent',
timestamp: '2015-12-03 01:06:59',
timestamp_offset: -180
}

Maintenance Reminder

{
    {
        "event": "vehicle_maintenance",
        "id": "8ZGwUTsMPoSVEMvbPcxUBx",
        "kind": "VehicleMaintenanceEvent",
        "timestamp": 2015-12-10 15: 00: 01,
        "timestamp_offset": 0,
        "car": {
            "battery_level": 12.4,
            "fuel_level": 80,
            "id": "Ry2RhXHszGu",
            "key": "agpzfnp1YmllLXFhcjcLEgdBY2NvdW50IhZDclRMWnVQZnE4VDR",
            "nickname": "2010 Mercedes-Benz E-Class",
            "vin": "WDDHF8HB0AA115852"
        },
        "maintenance": {
            "description": "Keep your oil fresh for a healthy engine.",
            "id": "9fp553DVRNf",
            "key": "agpzfnp1YmllLXFhclwLEgdBY2NvdW50IhZDclRMWnVQZnE4VDRTRzRVS1dLcUtWDAsSA0NhciIL",
            "next_service_date": 2015-12-10,
            "next_service_miles": null,
            "summary": "Oil Change"
        },
        "timestamp": "2015-12-10T15:00:01+00:00"
    }
}

Payload Security

All webhook payloads requests include an additional security header named, Zubie-Signature. This header is used to validate Zubie as the source of the inbound post.

The signature value is a base 64 encoded HMAC digest hash, which is generated from the application’s secret key and the web hook payload string. Upon receipt of a web hook post, generate your own hash for the given payload using your secret key and compare to the request header. Discard any requests fail to pass the comparison.

For examples on how to generate the hash in various languages, check out these HMAC examples.

Samples

node.js


payload = req.body;
hash = crypto.createHmac('SHA256', "1buvdm8ZkK49ptKkqz8b4x2ebphqeSr1").update(payload).digest('base64');

For additional examples on how to generate the hash in various languages, check out these HMAC examples.

Top