Webhooks
Webhooks allow developers to receive events as they occur, greatly simplifying the overhead for loading data and polling through restful API endpoints for changes in data.
To enable webhooks:
- Login to the ZINC developer portal.
- Select the application you wish to change and check “enable webhooks.”
- Enter your secure server side URL endpoint and specify the types of events you wish to receive. (ex: https://myapp.mycompany.com/zubie)
Using webhook data:
You will receive an HTTP POST with a JSON body containing details about the event. Each post contains:
- user_key : the unique identifier for the user that has granted your app permission
- account_key: the unique identifier for the account
- event: the type of event
- timestamp: UTC with local offset
Additional attributes/objects specific to that event type (see below). Note we also include user_id and account_id for legacy integrations.
Development Tips
You can use a service like RequestBin or Webhook.site to inspect webhooks for events in your test account (requires an active device)
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.
node.js sample
payload = req.body; hash = crypto.createHmac('SHA256', "1buvdm8ZkK49ptKkqz8b4x2ebphqeSr1").update(payload).digest('base64');
For examples on how to generate the hash in various languages, check out these HMAC examples.
Event Types
Driving Activity
Vehicle Health
Driving Behavior
Sample Payloads
Place Arrival
vehicle_geofence_arrival
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "point": { "acceleration": -4.518611309949892, "timestamp": "2019-09-27T13:10:14-04:00", "id": 1569604214, "longitude": -79.9288233333, "gps_quality": 1.9, "latitude": 32.8046533333, "speed_by_second": [], "key": "sample_trip_point_key", "gps_timestamp": null, "rpm": 1651, "heading": 98, "speed": 16.155610843546196 }, "user_key": "sample_user_key", "timestamp": "2019-09-27T13:10:14-04:00", "account_key": "sample_account_key", "geofence": { "id": "PkrQ8Gatk9i", "radius": 0.5, "name": "Ravanel", "key": "sample_geofence_key", "address": "Arthur Ravenel Jr Bridge, Charleston, SC 29403, USA" }, "car": { "battery_level": 12.4, "vin": "5FNRL38249B044393", "longitude": -79.9288233333, "key": "sample_car_key", "latitude": 32.8046533333, "fuel_level": 43, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "event": "vehicle_geofence_arrival" }
Place Departure
vehicle_geofence_departure
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "point": { "acceleration": -4.9659985683607735, "timestamp": "2019-09-27T13:30:49-04:00", "id": 1569605449, "longitude": -79.7961033333, "gps_quality": 1.5, "latitude": 32.85818, "speed_by_second": [], "key": "sample_trip_point_key", "gps_timestamp": null, "rpm": 1914, "heading": 49, "speed": 18.019719787032297 }, "user_key": "sample_user_key", "timestamp": "2019-09-27T13:30:49-04:00", "account_key": "sample_account_key", "geofence": { "id": "aNYmk42mZ63", "radius": 0.1, "name": "12286 N Hwy 17", "key": "sample_geofence_key", "address": "12286 N Hwy 17, Mt Pleasant, SC 29466, USA" }, "car": { "battery_level": 12.4, "vin": "5FNRL38249B044393", "longitude": -79.7961033333, "key": "sample_car_key", "latitude": 32.85818, "fuel_level": 43, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "event": "vehicle_geofence_departure" } }
Trip Start
trip_start
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "timestamp": "2019-09-27T13:00:00-04:00", "account_key": "sample_account_key", "event": "trip_start", "car": { "battery_level": 12.4, "vin": "5FNRL38249B044393", "longitude": -79.7710723333, "key": "sample_car_key", "latitude": 32.8542136667, "fuel_level": 84, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "trip": { "speeding_city_minor_count": null, "ended_timestamp": null, "idle_time": null, "fuel_cost_currency_code": "USD", "ended_latitude": null, "points_hwy_count": null, "hard_brakes": 0, "id": "123456", "speeding_hwy_major_count": null, "fuel_cost": null, "rapid_accels": 0, "speeding_hwy_minor_count": null, "started_longitude": null, "ended_longitude": null, "max_speed": null, "started_address": null, "key": "sample_trip_key", "distance": null, "points_city_count": null, "started_timestamp": "2019-09-27T13:00:00-04:00", "speeding_city_major_count": null, "ended_address": null, "started_latitude": null } }
Trip End
trip_end
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "timestamp": "2019-09-27T13:35:35-04:00", "account_key": "sample_account_key", "event": "trip_end", "car": { "battery_level": 11.8, "vin": "5FNRL38249B044393", "longitude": -79.7709333333, "key": "sample_car_key", "latitude": 32.8544866667, "fuel_level": 43, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "trip": { "speeding_city_minor_count": null, "ended_timestamp": "2019-09-27T13:35:35-04:00", "idle_time": 0, "fuel_cost_currency_code": "USD", "ended_latitude": 32.8544833333, "points_hwy_count": null, "hard_brakes": 0, "id": "123456", "speeding_hwy_major_count": null, "fuel_cost": 2.54, "rapid_accels": 0, "speeding_hwy_minor_count": null, "started_longitude": null, "ended_longitude": -79.77094, "max_speed": 52.81642006543949, "started_address": null, "key": "sample_trip_key", "distance": 14.369830191680585, "points_city_count": null, "started_timestamp": "2019-09-27T13:00:00-04:00", "speeding_city_major_count": null, "ended_address": null, "started_latitude": null } }
Trip Tagged
trip_tagged
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "timestamp": "2019-09-27T20:29:15+00:00", "account_key": "sample_account_key", "trip": { "speeding_city_minor_count": 0, "ended_timestamp": "2019-09-27T13:35:35-04:00", "idle_time": 0, "fuel_cost_currency_code": "USD", "ended_latitude": 32.8544833333, "points_hwy_count": 3, "hard_brakes": 0, "id": "123456", "speeding_hwy_major_count": 0, "fuel_cost": 2.54, "rapid_accels": 0, "speeding_hwy_minor_count": 0, "started_longitude": null, "ended_longitude": -79.77094, "max_speed": 52.81642006543949, "started_address": null, "key": "sample_trip_key", "distance": 14.369830191680585, "points_city_count": 15, "started_timestamp": "2019-09-27T13:00:00-04:00", "speeding_city_major_count": 1, "ended_address": { "city": "Mt Pleasant", "state": "SC", "street": "1204 Cutler Ln" }, "started_latitude": null }, "tag": { "value": "business" }, "user_key": "sample_user_key", "event": "trip_tagged" }
Vehicle Location Update
vehicle_location_updated
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "car": { "battery_level": 12.4, "vin": "5FNRL38249B044393", "longitude": -79.944845, "key": "sample_car_key", "latitude": 32.8036916667, "fuel_level": 43, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "user_key": "sample_user_key", "timestamp": "2019-09-27T13:08:05-04:00", "event": "vehicle_location_update", "account_key": "sample_account_key" }
Trouble Codes
vehicle_trouble_code
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample-user-key", "timestamp": "2019-09-27T14:00:00-04:00", "account_key": "sample_account_key", "trouble_code": { "code": "P0900", "description": "Clutch Actuator Circuit/Open", "repair_cost_low": null, "repair_cost_high": null, "detailed_description": "The Clutch locks the transmission and engine together. On some vehicles the clutch is electronically controlled by the Transmission Control Module (TCM). If the clutch does not operate as requested, code P0900 will be set.", "severity": 1 }, "car": { "battery_level": 11.8, "vin": "5FNRL38249B044393", "longitude": -79.7709333333, "key": "sample_car_key", "latitude": 32.8544866667, "fuel_level": 18, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "event": "vehicle_trouble_code" }
Trouble Code Cleared
vehicle_trouble_code_cleared
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample-user-key", "timestamp": "2019-09-27T15:00:00-04:00", "account_key": "sample_account_key", "trouble_code": { "code": "P0900", "description": "Clutch Actuator Circuit/Open", "repair_cost_low": null, "repair_cost_high": null, "detailed_description": "The Clutch locks the transmission and engine together. On some vehicles the clutch is electronically controlled by the Transmission Control Module (TCM). If the clutch does not operate as requested, code P0900 will be set.", "severity": 1 }, "car": { "battery_level": 11.8, "vin": "5FNRL38249B044393", "longitude": -79.7709333333, "key": "sample_car_key", "latitude": 32.8544866667, "fuel_level": 18, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "event": "vehicle_trouble_code_cleared" }
Low Battery
vehicle_low_battery
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "account_key": "sample_account_key", "event": "vehicle_low_battery", "timestamp": "2019-02-20T05:59:35-05:00", "vehicle": { "battery_level": 9.3, "fuel_level": 4, "key": "sample_vehicle_key", "nickname": "Pearl", "vehicle_location": { "point": { "lat": 32.882843, "lon": -80.036172 } }, "vin": "JM3TCADY5G0107976" } }
Low Fuel
vehicle_fuel_low
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "car": { "battery_level": 11.8, "vin": "5FNRL38249B044393", "longitude": -79.7709333333, "key": "sample_car_key", "latitude": 32.8544866667, "fuel_level": 18, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "user_key": "sample_user_key", "timestamp": "2019-09-27T13:35:35-04:00", "event": "vehicle_fuel_low", "account_key": "sample_account_key" }
Maintenance Reminder
vehicle_maintenance
{ "event": "vehicle_maintenance", "id": "8ZGwUTsMPoSVEMvbPcxUBx", "kind": "VehicleMaintenanceEvent", "timestamp": 2019-12-10 15:00:01, "timestamp_offset": 0, "car": { "battery_level": 12.4, "fuel_level": 80, "id": "Ry2RhXHszGu", "key": "sample_car_key", "nickname": "2010 Mercedes-Benz E-Class", "vin": "WDDHF8HB0AA115852" }, "maintenance": { "description": "Keep your oil fresh for a healthy engine.", "id": "9fp553DVRNf", "key": "sample_maintenance_event_key", "next_service_date": 2015-12-10, "next_service_miles": null, "summary": "Oil Change" }, "timestamp": "2019-12-10T15:00:01+00:00" }
Hard Brakes
trip_hard_brake
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "point": { "acceleration": -7.739799570508232, "timestamp": "2019-09-27T16:07:43-04:00", "id": 1569614863, "longitude": -76.618015, "gps_quality": 1.0, "latitude": 39.174313, "speed_by_second": [], "key": "sample_trip_point_key", "gps_timestamp": null, "rpm": 784, "heading": 193, "speed": 0.0 }, "user_key": "sample_user_key", "timestamp": "2019-09-27T16:07:43-04:00", "account_key": "sample_account_key", "event": "trip_hard_brake", "car": { "battery_level": 11.8, "vin": "5FNRL38249B044393", "longitude": -76.618015, "key": "sample_car_key", "latitude": 39.174313, "fuel_level": 0, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "trip": { "speeding_city_minor_count": null, "ended_timestamp": null, "idle_time": null, "fuel_cost_currency_code": "USD", "ended_latitude": null, "points_hwy_count": null, "hard_brakes": 0, "id": "1345679", "speeding_hwy_major_count": null, "fuel_cost": null, "rapid_accels": 0, "speeding_hwy_minor_count": null, "started_longitude": -76.620455, "ended_longitude": null, "max_speed": 41.01039675669419, "started_address": { "city": "Glen Burnie", "state": "MD", "street": "7327 Ritchie Hwy" }, "key": "sample-trip-key", "distance": null, "points_city_count": null, "started_timestamp": "2019-09-27T16:00:00-04:00", "speeding_city_major_count": null, "ended_address": null, "started_latitude": 39.169077 } }
Severe Hard Brake
trip_severe_hard_brake
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "point": { "acceleration": -20.132426628489622, "timestamp": "2019-09-27T15:52:01-05:00", "id": 1569617521, "longitude": -93.184717, "gps_quality": 0.6, "latitude": 44.456667, "speed_by_second": [], "key": "sample_trip_point_key", "gps_timestamp": null, "rpm": 2011, "heading": 267, "speed": 49.08820217846729 }, "user_key": "sample_user_key", "timestamp": "2019-09-27T15:52:01-05:00", "account_key": "sample_account_key", "event": "trip_severe_hard_brake", "car": { "battery_level": null, "vin": "JM1NB353130305984", "longitude": -93.184717, "key": "sample_car_key", "latitude": 44.456667, "fuel_level": 5, "nickname": "2003 Mazda MX-5 Miata", "id": "wJQbcGThypT" }, "trip": { "speeding_city_minor_count": 0, "ended_timestamp": null, "idle_time": null, "fuel_cost_currency_code": "USD", "ended_latitude": null, "points_hwy_count": 0, "hard_brakes": 1, "id": "1569618841333", "speeding_hwy_major_count": 0, "fuel_cost": null, "rapid_accels": 1, "speeding_hwy_minor_count": 0, "started_longitude": -93.144383, "ended_longitude": null, "max_speed": 49.08820217846729, "started_address": { "city": "Northfield", "state": "MN", "street": "1599 Lindberg Ct" }, "key": "sample_trip_key", "distance": null, "points_city_count": 46, "started_timestamp": "2019-09-27T15:41:47-05:00", "speeding_city_major_count": 0, "ended_address": null, "started_latitude": 44.444 } }
Rapid Acceleration
trip_rapid_accel
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "point": { "acceleration": 7.113457408733, "timestamp": "2019-09-27T15:50:19-05:00", "id": 1569617419, "longitude": -93.164, "gps_quality": 0.8, "latitude": 44.455117, "speed_by_second": [], "key": "sample_trip_point_key", "gps_timestamp": null, "rpm": 2793, "heading": 268, "speed": 6.835066126115699 }, "user_key": "sample_user_key", "timestamp": "2019-09-27T15:50:19-05:00", "account_key": "sample_account_key", "event": "trip_rapid_accel", "car": { "battery_level": null, "vin": "JM1NB353130305984", "longitude": -93.164, "key": "sample-trip-point-key", "latitude": 44.455117, "fuel_level": 5, "nickname": "2003 Mazda MX-5 Miata", "id": "wJQbcGThypT" }, "trip": { "speeding_city_minor_count": null, "ended_timestamp": null, "idle_time": null, "fuel_cost_currency_code": "USD", "ended_latitude": null, "points_hwy_count": null, "hard_brakes": 1, "id": "1234566", "speeding_hwy_major_count": null, "fuel_cost": null, "rapid_accels": 0, "speeding_hwy_minor_count": null, "started_longitude": -93.144383, "ended_longitude": null, "max_speed": 31.68985203926369, "started_address": { "city": "Northfield", "state": "MN", "street": "1599 Lindberg Ct" }, "key": "sample_trip_key", "distance": null, "points_city_count": null, "started_timestamp": "2019-09-27T15:41:47-05:00", "speeding_city_major_count": null, "ended_address": null, "started_latitude": 44.444 } }
Overspeeding
trip_over_speeding
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "account_key": "sample_account_key", "event": "trip_over_speeding", "timestamp": "2019-09-27T15:59:42-05:00" "point": { "acceleration": 2.572476735862563, "gps_quality": 0.6, "gps_timestamp": null, "heading": 2, "key": "sample_trip_point_key", "point": { "lat": 44.49585, "lon": -93.291433 }, "rpm": 3362, "speed": 81.39942386555968, "speed_by_second": null, "timestamp": "2019-09-27T15:59:42-05:00" }, "trip": { "distance": null, "end_point": null, "fuel_cost": null, "fuel_cost_currency_code": "USD", "hard_accel_count": 1, "hard_brake_count": 2, "idle_seconds": null, "key": "sample_trip_key", "points_city_count": 46, "points_hwy_count": null, "speeding_city_major_count": null, "speeding_city_minor_count": null, "speeding_hwy_major_count": null, "speeding_hwy_minor_count": null, "start_point": { "address": { "city": "Northfield", "state": "MN", "street": "1599 Lindberg Ct", "zipcode": null }, "point": { "lat": 44.444, "lon": -93.144383 }, "timestamp": "2019-09-27T15:41:47-05:00" }, "top_speed": 81.39942386555968 }, "vehicle": { "battery_level": null, "fuel_level": 5, "key": "sample_vehicle_key", "nickname": "2003 Mazda MX-5 Miata", "vehicle_location": { "point": { "lat": 44.49585, "lon": -93.291433 } }, "vin": "JM1NB353130305984" } }
Vehicle Schedule Exception
vehicle_schedule_exception
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "schedule": { "category": "working_hours", "name": "5AM-6AM Mon-Fri" }, "user_key": "sample_user_key", "timestamp": "2019-09-27T14:00:00-04:00", "account_key": "sample_account_key", "event": "vehicle_schedule_exception", "car": { "battery_level": 11.8, "vin": "5FNRL38249B044393", "longitude": -79.7709333333, "key": "sample_car_key", "latitude": 32.8544866667, "fuel_level": 18, "nickname": "HO787189", "id": "uZzLznvZLk8" }, "trip": { "speeding_city_minor_count": null, "ended_timestamp": null, "idle_time": null, "fuel_cost_currency_code": "USD", "ended_latitude": null, "points_hwy_count": null, "hard_brakes": 0, "id": "1569616223282", "speeding_hwy_major_count": null, "fuel_cost": null, "rapid_accels": 0, "speeding_hwy_minor_count": null, "started_longitude": -79.7709333333, "ended_longitude": null, "max_speed": null, "started_address": { "city": "Mt Pleasant", "state": "SC", "street": "1204 Cutler Ln" }, "key": "sample-trip-key", "distance": null, "points_city_count": null, "started_timestamp": "2019-09-27T14:00:00-04:00", "speeding_city_major_count": null, "ended_address": null, "started_latitude": 32.8544866667 } }
Device Activated
device_claim_success
{ "claim": { "id": "8ynaSh6829G", "key": "sample_claim_key" }, "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "timestamp": "2019-09-27T16:53:25-04:00", "account_key": "sample_account_key", "car": { "battery_level": null, "vin": "JM1NB353130305984", "longitude": -93.202267, "key": "sample_car_key", "latitude": 44.46265, "fuel_level": 5, "nickname": "2003 Mazda MX-5 Miata", "id": "wJQbcGThypT" }, "device": { "serial": "SM2MVRW9", "id": "3bHgzuzQhNpkZbw8uFuKX5", "key": "sample_device_key" }, "event": "device_claim_success" }
Device Unplugged
device_unplug
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "account_key": "sample_account_key", "device": { "key": "agpzfnp1YmllLXFhciILEgZEZXZpY2UiFmFHWTRXdkFGcDhVYmtjRE5SNlg0QnkM", "serial": "182400007" }, "event": "device_unplug", "timestamp": "2019-02-20T19:00:52-05:00", "vehicle": { "battery_level": 9.9, "fuel_level": 4, "key": "agpzfnp1YmllLXFhcjcLEgdBY2NvdW50IhZDclRMWnVQZnE4VDRTRzRVS1dLcUtWDAsSA0NhciILTjR1NFBNY0RycDQM", "nickname": "Pearl", "vehicle_location": { "point": { "lat": 32.88288, "lon": -80.036206 } }, "vin": "JM3TCADY5G0107976" } }
Device Reconnect
device_reconnect
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "account_key": "sample_account_key", "device": { "key": "agpzfnp1YmllLXFhciILEgZEZXZpY2UiFmFHWTRXdkFGcDhVYmtjRE5SNlg0QnkM", "serial": "182400007" }, "event": "device_reconnect", "last_gasp_timestamp": "2019-02-20T22:34:28-04:00", "timestamp": "2019-06-12T13:59:44-04:00" }
Device Moved to New Vehicle
device_vehicle_change
{ "user_id": "vxXDeLFxMPHEUfNcG8BmLB", "account_id": "CrTLZuPfq8T4SG4UKWKqKV", "user_key": "sample_user_key", "account_key": "sample_account_key", "device": { "key": "sample_device_key", "serial": "182400007" }, "event": "device_vehicle_change", "timestamp": "2019-02-20T19:00:52-05:00", "vehicle": { "battery_level": 9.9, "fuel_level": 4, "key": "sample_vehicle_key", "nickname": "Pearl", "vehicle_location": { "point": { "lat": 32.88288, "lon": -80.036206 } }, "vin": "JM3TCADY5G0107976" } }