Guide to Motive Webhooks: Features and Best Practices
Motive, formerly KeepTruckin, runs the electronic logging devices, vehicle gateways and dashcams in a lot of commercial fleets. Its webhooks push what those devices and drivers report to your systems as it happens: vehicle locations, engine fault codes, hours-of-service violations, geofence crossings, speeding events and disconnected hardware. If you run dispatch, maintenance or safety software alongside Motive, webhooks save you from polling the API for every vehicle.
This guide covers how Motive webhooks are created and signed, the activation test request, the actions you can subscribe to, how Motive treats your responses, and the best practices for running a Motive receiver in production.
What are Motive webhooks?
Motive calls them company webhooks. You create them through the Motive API (partner apps can also add them in Motive's developer portal), giving each one a URL, a shared secret and a list of actions. Whenever one of those actions happens in your fleet, Motive sends an HTTP POST to the URL.
The body is a single JSON object. Its action field names the event, and the rest of the object is the resource itself, flattened beside it. Most actions also include a trigger field, which tells you whether the resource was created or updated.
Every request is signed. The X-KT-Webhook-Signature header holds a hex HMAC-SHA1 of the JSON body, computed with the webhook's shared secret.
Motive webhook features
| Feature | Details |
|---|---|
| Configuration | Motive API: create, list, fetch and update company webhooks |
| Subscription | An actions array per webhook |
| Body | A flat JSON object with action, usually trigger, and the resource's fields |
| Format | JSON only |
| Signature header | X-KT-Webhook-Signature |
| Scheme | HMAC-SHA1, hex digest |
| Signed content | The raw JSON body, nothing else |
| Secret | One shared secret per webhook |
| Replay window | None. No timestamp is signed |
| Success | 200 or 201, final |
| Bad signature | Return 403. Motive treats it as invalid and doesn't retry |
| Timeout | 3 seconds |
| Retries | Other 4xx/5xx and timeouts are retried after 1 minute, 1 hour and 6 hours |
| Activation | A test request must receive 200 or 201 |
| Limits | One active webhook per action and URL, two per action |
| Delivery history | The API can list past webhook requests and trigger a webhook |
Common actions
Motive lists around twenty actions. These are the ones most integrations use:
| Action | Triggered when |
|---|---|
vehicle_location_updated | A vehicle location arrives that is newer than the current one |
vehicle_ | Any vehicle location arrives, whether or not it's the newest |
vehicle_upserted | A vehicle is created or updated |
fault_code_opened / fault_code_closed | A fault code opens or closes on a vehicle |
user_upserted | A user, such as a driver, is created or updated |
inspection_ | An inspection report's defects change |
hos_violation_upserted | An hours-of-service violation is created or updated |
vehicle_geofence_event / asset_geofence_event | A vehicle or asset enters or leaves a geofence |
engine_toggle_event | An engine is turned on or off |
speeding_event_created / speeding_event_updated | A speeding event is created or updated |
driver_ / driver_ | A driver performance event is created or updated |
form_entry_upserted | A driver dispatch form entry is created or updated |
vehicle_ / vehicle_ | A vehicle gateway loses power or its connection, or comes back |
dashcam_disconnected | A dashcam is unplugged |
user_duty_status_updated | A driver's timecard status changes (documented on the Webhooks v2 page) |
A few of these behave differently from what their names suggest. inspection_ fires only for changes to an inspection's defects, so creating a clean inspection report sends nothing. vehicle_ sends every location, including late ones, so it's far busier than vehicle_location_updated. Speeding events can arrive minutes after the event itself.
Here is a trimmed fault_code_opened request from Motive's documentation:
{
"action": "fault_code_opened",
"trigger": "created",
"id": 123,
"code": "J1939",
"code_description": "Cargo Securement",
"status": "open",
"first_observed_at": "2017-01-01T12:45:33Z",
"last_observed_at": "2017-01-05T12:45:33Z",
"fmi": 5,
"code_label": "SPN-5610",
"fmi_description": "Abnormal rate of change",
"vehicle": {
"id": 1,
"number": "T123",
"make": "Kenworth",
"model": "379",
"vin": "ABC12345678909876"
},
"eld_device": { "id": 1, "identifier": "00000001", "model": "lbb-2" },
"network": "j1587/j1708"
}
Setting up Motive webhooks
- Call the Motive API's Create a new company webhook endpoint with:
url: your HTTPS endpointsecret: the shared secret. Motive generates one if you leave it blank, but it's simpler to set your own. The API reference says it must be 20 charactersformat:json, the only supported formatactions: the actions you want, for example["fault_code_ opened", "fault_ code_ closed"] enabled:true
- Store the secret server-side, for example as
MOTIVE_WEBHOOK_SECRET. - Make sure your endpoint answers Motive's test request with
200or201. Motive won't enable the webhook otherwise.
Partner apps registered in Motive's developer portal can also add a webhook from the app's Webhooks tab, with the same name, URL, secret and action fields. That form only accepts URLs whose top-level domain is two to five letters long, so it rejects a Hookdeck https://hkdk.events/... URL. Use the equivalent https://events.hookdeck.com/e/<id> form instead, where <id> is the part after hkdk.events/.
Motive allows only one active webhook for the same action and URL, and at most two active webhooks per action. Activating a third for the same action fails.
Webhooks v2, which Motive enables for a company on request, keeps the same actions and signing but can also deliver to an AWS SQS queue or SNS topic. This guide covers HTTP delivery only.
The activation test request
Whenever you enable a webhook, change its URL or change its secret, Motive sends a test request and enables the webhook only if it gets 200 or 201 back.
Motive's documentation prints the body as [vehicle_, which isn't valid JSON. The real request is different. When we created a webhook for vehicle_location_updated and fault_code_closed, the test request was:
POST /webhooks/motive HTTP/1.1
Content-Type: application/json
User-Agent: Ruby
X-KT-Webhook-Signature: <hex HMAC-SHA1 of the body>
["vehicle_location_updated","fault_code_closed"]
The body is a valid JSON array of the webhook's actions, and it is signed the same way as real events. A receiver that verifies the signature first can answer it with 200. It has no action field, so don't hand it to your event processing.
With the URL pointing at Hookdeck, the test request is accepted and verified like any other, and the webhook enables.
Securing Motive webhooks
Compute a hex HMAC-SHA1 of the raw request body with the webhook's secret and compare it with X-KT-Webhook-Signature in constant time. Motive suggests responding with 403 when the signature doesn't match, which it treats as final.
const crypto = require('crypto');
const express = require('express');
function verifyMotiveSignature(rawBody, signatureHeader, secret) {
if (!signatureHeader || !secret) return false;
const expected = crypto.createHmac('sha1', secret).update(rawBody).digest('hex');
const received = Buffer.from(signatureHeader.trim().toLowerCase(), 'utf8');
const computed = Buffer.from(expected, 'utf8');
return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}
const app = express();
app.post('/webhooks/motive', express.raw({ type: '*/*' }), (req, res) => {
const secret = process.env.MOTIVE_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500); // fail closed
if (!verifyMotiveSignature(req.body, req.get('x-kt-webhook-signature'), secret)) {
return res.sendStatus(403); // Motive does not retry a 403
}
let payload;
try {
payload = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (Array.isArray(payload)) {
return res.sendStatus(200); // the activation test request: a list of actions
}
const { action, trigger } = payload; // e.g. fault_code_opened, created
// Store it, then process asynchronously. Motive waits only 3 seconds.
res.sendStatus(200);
});
The same check in Python:
import hashlib
import hmac
def verify_motive_signature(raw_body: bytes, signature_header, secret: str) -> bool:
if not signature_header or not secret:
return False
expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha1).hexdigest()
received = signature_header.strip().lower().encode("utf-8")
return hmac.compare_digest(received, expected.encode("utf-8"))
# In FastAPI: raw_body = await request.body()
# verify_motive_signature(raw_body, request.headers.get("x-kt-webhook-signature"),
# os.environ["MOTIVE_WEBHOOK_SECRET"])
Motive's documentation gives a test vector. With the secret d9d36bea41c44ae49d1bfc4a48ba2abe and the body ["fault_code_closed"], the signature is f04a8386a21a6cba0447024e83b3f0983352bb72. The bash and Ruby snippets on the same page pass the signature as the HMAC key instead of the secret, so don't copy them. This reproduces the vector:
printf '%s' '["fault_code_closed"]' | openssl dgst -sha1 -hmac d9d36bea41c44ae49d1bfc4a48ba2abe
Make Motive webhooks production-ready. Hookdeck Event Gateway verifies the
X-KT-Webhook-Signatureheader, answers inside Motive's 3-second window, and queues every fleet event so a slow or offline service doesn't lose it.
Motive webhook limitations and pain points
A 3-second window
The Problem: Requests your service handled are retried, or recorded as failed.
Why It Happens: Motive expects your server to accept the connection and respond within 3 seconds. After that, it assumes the request failed and schedules a retry, even if your handler finishes the work.
Workarounds:
- Verify, store and respond. Do everything else in a background job.
- Make processing idempotent, because timeouts lead to duplicate deliveries.
How Hookdeck Can Help: Hookdeck responds at its edge, well inside 3 seconds, and then delivers to your service with a timeout and retries you choose.
Three retries, then nothing
The Problem: An outage of more than a few hours loses events.
Why It Happens: Motive retries a failed request after 1 minute, 1 hour and 6 hours. Once those are used up, the documentation describes no further attempts. A 403 isn't retried at all.
Workarounds:
- Only return
403for a genuine signature failure. Use5xxfor errors you want retried. - After an incident, use the API's list of webhook requests to see what failed, and rebuild state from the API.
How Hookdeck Can Help: Hookdeck stores every request when it arrives, so an outage on your side doesn't run down Motive's retries. You can replay any event once your service is back.
High-volume location actions
The Problem: Location webhooks swamp the handler, and the slow response triggers retries that add even more traffic.
Why It Happens: vehicle_location_updated fires every time a vehicle reports a newer location, and vehicle_ fires for every location at all. Across a fleet that's a steady stream of requests, each of which must be answered within 3 seconds.
Workarounds:
- Subscribe to the location actions on a separate webhook and endpoint from your business events.
- Prefer
vehicle_location_updatedunless you need every point, including late ones. - Write locations to a queue or append-only store instead of doing work per request.
How Hookdeck Can Help: Hookdeck absorbs bursts and delivers to your service at a maximum rate you set, and filters can route location actions to a different destination from fault codes or safety events.
Undocumented details in the test request
The Problem: A new webhook won't enable, or your logs fill with errors from a request that isn't a real event.
Why It Happens: Motive's documentation describes the activation test body as [vehicle_ and doesn't say whether it's signed. In practice it's a signed JSON array of the webhook's actions, not an event object. Handlers that expect an action field throw, return a 5xx, and the webhook stays disabled.
Workarounds:
- Verify the signature as usual, then answer a body that's a JSON array with
200without processing it. - If you create webhooks in the developer portal, use a URL with a top-level domain of five letters or fewer.
How Hookdeck Can Help: Hookdeck verifies the test request, answers it straight away and stores it where you can inspect its headers and body, so the webhook enables. You can then use a filter on body.action to keep it away from your destination.
Best practices
Verify against the raw body
Mount express.raw() on the webhook route and parse only after verification. In FastAPI, read await request.body(). Re-serialised JSON won't match the signature.
Return the status codes Motive expects
Use 200 for success, 403 only for a bad signature, and 5xx for failures you want retried. Motive's documentation lists 200 and 201 as success, so don't rely on other 2xx codes.
Process each event once
Motive leaves it to the receiver to make sure a request is processed only once, and documents no event ID header. Build a key from action and the resource's id, plus a field that changes between updates, such as a timestamp in the body, and record it before processing. See our guide to webhook idempotency.
Dispatch on action, then trigger
Switch on action first. For the _upserted actions, use trigger to tell creates from updates. Not every action includes trigger: the speeding_event_created example has none at the top level, only a trigger of speeding inside metadata. Don't depend on it everywhere.
Acknowledge fast and process asynchronously
Verify, store, return 200, and process afterwards. See why to process webhooks asynchronously.
Conclusion
Motive signs every company webhook with a hex HMAC-SHA1 of the body in X-KT-Webhook-Signature, using the webhook's shared secret, so verification takes a few lines. The harder parts are operational: a 3-second timeout, three retries over about seven hours, a test request that must succeed before the webhook is enabled, and location actions that can produce a lot of traffic.
Hookdeck Event Gateway sits in front of your receiver, verifies every signature, answers within Motive's window, and holds each event until your service has processed it.
Get started with Hookdeck for free and handle Motive webhooks reliably in minutes.