> For the complete documentation index, see [llms.txt](https://docs.high-mobility.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.high-mobility.com/docs/webhooks.md). # 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 `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. ### Frequently asked questions #### Delivery and reliability **What HTTP response is expected from our endpoint?** Any HTTP `2xx` response is considered successful. A specific status code such as `200 OK` is not required, and no response body is necessary. **Does the initial ping require a successful response to save the webhook configuration?** No. Webhook configuration is saved independently of whether the ping is delivered successfully. However, your endpoint should return a `2xx` response to acknowledge the ping. **What are the webhook delivery timeouts?** Webhook deliveries have two separate timeouts: * **Connection timeout:** 10 seconds to establish a connection. * **Response timeout:** 10 seconds to receive a response after the connection is established. If either timeout is exceeded, the delivery is considered failed. **Are failed webhook deliveries retried?** Yes. If a delivery fails due to a non-`2xx` response, timeout, or connection error, it is automatically retried every 10 minutes. * **Production:** Up to 200 total delivery attempts. * **Sandbox:** Up to 5 total delivery attempts. Once the maximum number of attempts is reached, automatic retries stop. **Can events be delivered more than once or arrive out of order?** Yes. Webhook consumers should be designed to handle duplicate deliveries and out-of-order events. * The `X-HM-Delivery` header identifies a delivery and can be used to recognize retries of that delivery. * Separately generated events may represent the same underlying change but have different delivery identifiers. * Event ordering is not guaranteed, including for events associated with the same VIN. We recommend implementing idempotent event processing and checking the latest clearance state when event ordering matters. #### Security and signature verification **How is the webhook signature calculated?** The `X-HM-Signature-256` header contains an HMAC-SHA256 signature calculated using the configured webhook secret and the exact raw request body bytes. The header has the following format: `sha256=` Signature verification should use the raw request body before any JSON parsing or re-serialization. **Is the webhook secret specific to each project?** The secret is configured per webhook configuration, which is associated with a project. The same secret can be reused across multiple projects, but we recommend using a unique secret for each project to reduce shared security exposure. When handling webhooks from multiple projects, also verify that the application identifier in the signed payload matches the expected project. #### Event availability and timing **Is `fleet_clearance_changed` supported by all vehicle brands and clearance flows?** All implemented fleet-brand handlers support notifications for clearance approvals, rejections, and revocations. Intermediate states such as `revoking` and `canceling` do not trigger a `fleet_clearance_changed` webhook. **How quickly are webhook events sent after a clearance status changes?** Webhook events are queued as soon as the relevant clearance status change is processed by our platform. Events are not intentionally batched. However, delivery is asynchronous, so a delay between the status change and webhook delivery is possible. #### Testing and networking **Can webhooks be tested using simulated vehicles?** Yes. Sandbox clearance events are supported and can be used to test webhook integrations. Internal testing tools also support triggering test events and ping deliveries. Availability of these controls to customers may vary. **Are webhook deliveries sent from fixed IP addresses?** No. Webhook deliveries are not restricted to a published, fixed set of source IP addresses. We recommend verifying the `X-HM-Signature-256` header to authenticate incoming webhook requests rather than relying on IP allowlisting. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.high-mobility.com/docs/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.