Webhooks

Use webhooks to get notified of vehicle clearance events without polling the API

Webhooks allow your app to subscribe to different clearance 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 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 "API Credentials" and then "Webhooks" section

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. Click on "Update".

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	DESCRIPTION
fleet_clearance_changed	Sent when the clearance status of a fleet vehicle changes. The new state is included in the actionkey. If there is further details such as a reason for a vehicle to be rejected, it's included in the detailfield.
ping	Sent every time when the webhook is configured or changed.

Delivery request

Delivery headers

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

NAME	VAULE
X-HM-Signature-256	A signature that is computed based on the payload and the secret. This follows the format "sha256=SIGNATURE".
X-HM-Delivery	A unique delivery identifier.
User-Agent	"HM-Webhook/1.2.0"
Content-Type	"application/json"

DEPRECATION OF SHA1

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

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.

const crypto = require('crypto');

function verifySecret(payload, SECRET, SIGNATURE_HEADER) {
  const signature = 'sha256=' + crypto
    .createHmac('sha256', SECRET)
    .update(payload, 'utf8')
    .digest('hex');

  // Prevent timing attacks
  const verified = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(SIGNATURE_HEADER)
  );

  return verified;
}

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.
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.
	detail	Further information of the change, such as a reason.
application		Object
	id	The ID of the application registered in the platform.

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

{
    "vehicle": {
        "vin": "1HMCF6112HA3FBBCC"
    },
    "event": {
        "type": "fleet_clearance_changed",
        "action": "rejected",
        "detail": "invalid VIN",
        "received_at": "2025-06-19T09:49:08.386159Z"
    },
    "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.