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

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

  1. Go to the Apps page and click on your app.
  2. Select the "webhook" tab.
  3. Enter the URL that should be subscribed. Note that only secure (HTTPS) URLs are accepted.
  4. 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.
  5. Choose the events that should trigger the webhook.
  6. 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.

TypeProduction availabilityDescription
accident_reportedBMW, MINI, Peugeot, Citroën, DS, Opel and VauxhallSent when the BMW/MINI Accident Assistance Call is triggered, either manually by the driver or automatically by the vehicle.
authorization_changedBMW, MINI, Ford, Mercedes-Benz, Peugeot, Citroën, DS, Opel and VauxhallSent when the authorization is revoked. Also sent when BMW/MINI authorization is, as it is asynchronous.
battery_guard_warningBMW, MINI, FordSent when the 12V battery runs low.
breakdown_reportedBMW, MINISent when the driver calls the roadside assistance service.
emergency_reportedBMW, MINI, Peugeot, Citroën, DS, Opel and VauxhallSent when the BMW/MINI Intelligent Emergency Call is triggered.
engine_changedPeugeot, Citroën, DS, Opel and VauxhallTriggered when the engine status changes
dashboard_lights_changedFord, Peugeot, Citroën, DS, Opel and VauxhallSent when the warning/malfunction indicator lights change.
fleet_clearance_changedBMW, MINI, Mercedes-Benz, Peugeot, Citroën, DS, Opel and VauxhallSent when the clearance status of a fleet vehicle changes. The new state is included in the action key.
maintenance_changedBMW, MINISent when the Diagnostics property Condition Based Services changes.
ping-Sent every time when the webhook is configured or changed.
trip_startedNot availableSent every time a vehicle starts a trip.
trip_endedNot availableSent when a vehicle ends a trip.
ignition_changedFordSent when the ignition state changes — e.g. at the beginning and the end of a trip.
vehicle_location_changedBMW, MINI, Ford, Peugeot, Citroën, DS, Opel and VauxhallSent when the vehicle location changes.

Emulator

When the trip_started and *trip_ended• webhooks are used with the car emulator, the events are triggered when a simulation is being started or stopped.

Delivery request

Delivery headers

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

NameValue
X-HM-SignatureA signature that is computed based on the payload and the secret. This follows the format "sha1=SIGNATURE".
X-HM-Event deprecatedThe event name.
X-HM-DeliveryA unique delivery identifier.
User-Agent"HM-Webhook/1.0.0"
Content-Type"application/json"

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 = 'sha1=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), SECRET, payload)
  verified = Rack::Utils.secure_compare(signature, SIGNATURE_HEADER)
end

Delivery payload

The payload is a JSON object with the following keys.

KeyValue
vehicleObject
vinThe VIN of the vehicle. Set to "*" for the ping event.
serial_numberThe serial of the vehicle to be used with HMKit SDKs. Set to "*" for the ping event.
eventObject
typeWebhook event type from the above table.
received_atThe DateTime of when the event was received.
actionOptional field depending on the webhook type.
applicationObject
idThe ID of the application registered in the platform.
authorizationObject (only used for authorization_changed)
idThe authorization id that was provided during the OAuth2 consent flow.
ApplicationId deprecatedThe application ID that had the webhook configured.
VehicleSerialNumber deprecatedThe serial number of the vehicle that triggered the event. Set to "*" for the pingevent.

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.