# 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_location_received` | 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_report_upserted` | 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_performance_event_created` / `driver_performance_event_updated` | A driver performance event is created or updated |
| `form_entry_upserted` | A driver dispatch form entry is created or updated |
| `vehicle_gateway_disconnected` / `vehicle_gateway_disconnect_ended` | 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_report_upserted` fires only for changes to an inspection's defects, so creating a clean inspection report sends nothing. `vehicle_location_received` 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:

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

1. Call the Motive API's **Create a new company webhook** endpoint with:
  
  * `url`: your HTTPS endpoint
  * `secret`: 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 characters
  * `format`: `json`, the only supported format
  * `actions`: the actions you want, for example `["fault_code_opened", "fault_code_closed"]`
  * `enabled`: `true`
2. Store the secret server-side, for example as `MOTIVE_WEBHOOK_SECRET`.
3. Make sure your endpoint answers Motive's test request with `200` or `201`. 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_location_updated]`, 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:

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

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

```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:

```bash
printf '%s' '["fault_code_closed"]' | openssl dgst -sha1 -hmac d9d36bea41c44ae49d1bfc4a48ba2abe

```

> **Make Motive webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies the `X-KT-Webhook-Signature` header, 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](/docs/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 `403` for a genuine signature failure. Use `5xx` for 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_location_received` 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_updated` unless 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](/docs/destinations#set-a-max-delivery-rate) you set, and [filters](/docs/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_location_updated]` 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 `200` without 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](/docs/filters) 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](/webhooks/guides/implement-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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## 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](https://hookdeck.com) 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](https://dashboard.hookdeck.com/signup) for free and handle Motive webhooks reliably in minutes.