# Webhooks

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 `action`key. If there is further details such as a reason for a vehicle to be rejected, it's included in the `detail`field. |
| 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"                                                                                            |

{% hint style="info" %}
**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.
{% endhint %}

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. 

```javascript
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.

```json
{
    "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.