Webhooks

Webhooks allow your app to subscribe to different vehicle events and act on it. Once configured, the webhook will be triggered based on different vehicle events. This makes app implementations simpler, as it is no longer necessary to poll the Auto API in order to determine when states change.

Configure a webhook
Events
Delivery request
Recent deliveries

Configure a webhook

To configure the webhook for your app, you will need to follow these steps.

Go to the Apps page and click on your app.
Select the "webhook" tab.
Enter the URL that should be subscribed. Note that only secure (HTTPS) URLs are accepted.
Enter a secret string. This will be passed along with each webhook header so that you can verify its authenticity. It's recommended to use a random string generator with high entropy.
Choose the events that should trigger the webhook.
Check the "Activate" checkbox and then "Save".

Once saved the webhook will be triggered for the ping event. This is useful for checking that the subscription works. It's possible to redeliver the webhook as many times as you want for further tests.

Events

The following events are supported by the platform today. While all webhooks work with the emulators, note that the production availability is different for each carmaker.

Type	Production availability	Description
accident_reported	BMW, MINI	Sent when the BMW/MINI Accident Assistance Call is triggered, either manually by the driver or automatically by the vehicle.
authorization_changed	All driver consented brands	Sent when the authorization is revoked. Also sent when BMW/MINI authorization is, as it is asynchronous.
battery_guard_warning	BMW, MINI	Sent when the 12V battery runs low.
breakdown_reported	BMW, MINI	Sent when the driver calls the roadside assistance service.
emergency_reported	BMW, MINI	Sent when the BMW/MINI Intelligent Emergency Call is triggered.
fleet_clearance_changed	All fleet brands	Sent when the clearance status of a fleet vehicle changes. The new state is included in the `action` key.
maintenance_changed	BMW, MINI	Sent when the Diagnostics property Condition Based Services changes.
ping	-	Sent every time when the webhook is configured or changed.
vehicle_location_changed	BMW, MINI	Sent when the vehicle location changes.
fleet_geofence_notification	All fleet brands	Sent when the vehicle enters or exits a geofence.

Delivery request

Delivery headers

The following headers are included in the request sent out from our platform.

Name	Value
X-HM-Signature-256	A signature that is computed based on the payload and the secret. This follows the format "sha256=SIGNATURE".
X-HM-Event deprecated	The event name.
X-HM-Delivery	A unique delivery identifier.
User-Agent	"HM-Webhook/1.0.0"
Content-Type	"application/json"

DEPRECATION OF SHA1
We are still providing the header X-HM-Signature that uses SHA1, in order to give customer a chance with past implementation to migrate. However X-HM-Signature-256 should be used for a secure implementation.

Secret verification

Your server has to know about the secret that was configured for the webhook. Together with the payload the secret can be verified by using common crypto libraries. The following is an example to verify the signature in Ruby.

def verify_secret(payload)
  signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), SECRET, payload)
  verified = Rack::Utils.secure_compare(signature, SIGNATURE_HEADER)
end

Delivery payload

The payload is a JSON object with the following keys.

Key		Value
vehicle		Object
	vin	The VIN of the vehicle. Set to "" for the ping* event.
	serial_number	The serial of the vehicle to be used with HMKit SDKs. Set to "" for the ping* event.
event		Object
	type	Webhook event type from the above table.
	received_at	The DateTime of when the event was received.
	action	Optional field depending on the webhook type.
application		Object
	id	The ID of the application registered in the platform.
authorization		Object (only used for authorization_changed)
	id	The authorization id that was provided during the OAuth2 consent flow.
ApplicationId deprecated		The application ID that had the webhook configured.
VehicleSerialNumber deprecated		The serial number of the vehicle that triggered the event. Set to "" for the ping*	event.

Example webhook

The following example shows the JSON content of a vehicle_location_changed event being delivered.

{
    "vehicle": {
        "vin": "1HMCF6112HA3FBBCC",
        "serial_number": "BB5EAC44D33F205A87"
    },
    "event": {
        "type": "trip_started",
        "received_at": "2019-02-20T09:13:33.563772Z",
        "action": null
    },
    "application": {
        "id": "A77294AC8DA324FB46DA98921"
    }
}

Recent deliveries

It is possible to inspect recent deliveries in the bottom of the app details page. The last 10 deliveries will be shown and it's possible to see the headers and payloads for both the delivery and the response.