← API v2 Overview

Webhooks

Subscribe to events and receive a signed HTTP POST the moment something changes, instead of polling. A subscription belongs to your business and is managed entirely through the API.

How It Works

1. Create a subscription with POST /webhooks, giving an HTTPS endpoint and the events you want. The signing secret is returned once, in that response.
2. When a matching event occurs, MotorDesk queues a delivery and sends it to your endpoint as a JSON POST, signed with your secret.
3. Your endpoint verifies the signature and responds with any 2xx status to acknowledge receipt. A non-2xx response, a timeout, or a connection error is treated as a failed delivery and retried.

Delivery is near-real-time (typically a few seconds behind the event) and runs out of band, so a slow or failing endpoint never affects the dashboard or the API write that produced the event.

Events

Event names are resource.action, for example vehicle.sold, lead.created, invoice.paid. Subscribe to specific events, or to "*" for all current and future events. The live catalogue (with the read scope each event requires) is available at GET /reference/webhook-events.

A subscription may only receive an event if its scope set includes that event's read scope (see Scopes and Payloads).

Payload

Each delivery is a JSON envelope. data is the same object you would get from that resource's GET endpoint, projected to the subscription's scopes. Deletion-style events (*.deleted, appointment.cancelled) carry only the id, because the record is gone or archived.

POST https://example.com/motordesk/webhook
Content-Type: application/json
X-MotorDesk-Signature: t=1781560330,v1=4f9c2b...e1
X-MotorDesk-Event: vehicle.sold
X-MotorDesk-Event-Id: evt_9b1d4c7a8f2e4a1b9c3d5e6f7a8b9c0d
X-MotorDesk-Delivery: 4812

{
  "id": "evt_9b1d4c7a8f2e4a1b9c3d5e6f7a8b9c0d",
  "event": "vehicle.sold",
  "api_version": "2.0",
  "created": 1781560330,
  "business": {
    "id": 576,
    "tag": "ABC123"
  },
  "data": {
    "id": 85574,
    "...": "the vehicle resource, as returned by GET /vehicles/{id}"
  }
}

The business object identifies which dealership the event belongs to. It is part of the signed body, so a single endpoint serving many dealers can route on it safely - no need for a per-business URL or to test each secret. The request headers carry the event name, the event id (also in the body), and the delivery id, so a receiver can route and log without parsing the body first.

Verifying Signatures

Every delivery is signed with your subscription secret so you can confirm it genuinely came from MotorDesk and was not tampered with or replayed. The X-MotorDesk-Signature header is Stripe-style:

X-MotorDesk-Signature: t=1781560330,v1=4f9c2b...e1

t is the Unix timestamp when the delivery was signed, and v1 is the HMAC-SHA256, as lowercase hex, of the string "{t}.{raw_body}" keyed with your secret. To verify:

1. Read the raw request body exactly as received, before any JSON parsing or re-encoding.
2. Split the header on commas to read t and v1.
3. Compute HMAC-SHA256(secret, t + "." + raw_body) and compare it to v1 using a constant-time comparison.
4. Reject the request if t is outside a tolerance window (for example five minutes) of your current time, to prevent replay.

// PHP
$secret    = 'whsec_...';
$payload   = file_get_contents('php://input'); // the raw body
$header    = $_SERVER['HTTP_X_MOTORDESK_SIGNATURE'];
parse_str(strtr($header, ',', '&'), $parts);   // t=..., v1=...
$expected  = hash_hmac('sha256', $parts['t'].'.'.$payload, $secret);
$valid     = (abs(time() - (int) $parts['t']) <= 300) && hash_equals($expected, $parts['v1']);
http_response_code($valid ? 200 : 400);

Verify the signature against the raw bytes before parsing the JSON, and only then trust the body.

Delivery, Retries and Failures

Deliveries are attempted with a 10-second timeout. Any 2xx response marks the delivery delivered; anything else (including a timeout or connection error) is a failed attempt and is retried with exponential backoff, up to roughly nine attempts spread over about 24 hours:

If a subscription accumulates sustained consecutive failures it is automatically disabled and the business is emailed; the failure counter resets to zero on any successful delivery. Re-enable a disabled subscription with PATCH /webhooks/{id} and {"status":"active"}, which clears the counter and resumes queued deliveries. Inspect recent attempts (status, response code, timing) with GET /webhooks/{id}/deliveries, and re-send a past delivery with POST /webhooks/{id}/deliveries/{delivery_id}/redeliver.

Ordering and Idempotency

Delivery is at-least-once: an endpoint may occasionally receive the same event more than once (for example when it acknowledges late, or a delivery is re-sent). Order is not guaranteed; a retried event can arrive after a newer one.

• Dedupe on the event id (id in the body, or the X-MotorDesk-Event-Id header). Re-deliveries of the same event keep the same id.
• Order by the created timestamp, or re-fetch the resource by id to get its current state, rather than assuming the payload is the latest.
• Respond quickly (within the 10-second timeout). Acknowledge with a 2xx and do slow work asynchronously.

Coalescing. A rapid burst of changes to the same record (for example uploading several photos in quick succession) is collapsed into a single *.updated delivery carrying the latest state, sent a few seconds after the activity settles - so you receive one event, not one per change. Discrete events (*.created, *.sold, payments, and similar) are never coalesced and are always delivered individually.

Scopes and Payloads

A subscription stores its own scope set, chosen at creation and limited to the scopes held by the API key that created it. That scope set does two things: it gates which events the subscription may receive, and it projects every payload. A subscription with only vehicles:read, for instance, receives the base vehicle object but never the pricing, cost or funding fields that vehicle-pricing:read unlocks. When scopes is omitted on create, it defaults to the minimal read scopes the chosen events require.

Security

• Endpoint URLs must use HTTPS.
• The signing secret is shown once, in the create (and rotate) response. Store it securely; it cannot be retrieved later. Rotate it with POST /webhooks/{id}/secret/rotate.
• Always verify the signature and enforce the timestamp tolerance before acting on a payload.
• Payloads are scope-gated per subscription, so a subscription never carries data beyond its own scopes.

Managing Subscriptions

Subscriptions are managed entirely through the API. Managing them needs webhooks:read or webhooks:write. Send a test ping at any time with POST /webhooks/{id}/ping to exercise your endpoint and signature handling. The subscription object and the full endpoint list follow.

The Webhook Object

Generated from the OpenAPI schema. Always matches the live API.

{
    "id": 0,
    "url": "",
    "description": "",
    "events": "",
    "scopes": [
        ""
    ],
    "status": "active",
    "secret_hint": "",
    "secret": "",
    "failure_count": 0,
    "last_status": "delivered",
    "last_delivery_at": 0,
    "created": 0,
    "updated": 0
}

Endpoints

{
    "success": true,
    "data": [
        {
            "id": 0,
            "url": "",
            "description": "",
            "events": "",
            "scopes": [
                ""
            ],
            "status": "active",
            "secret_hint": "",
            "secret": "",
            "failure_count": 0,
            "last_status": "delivered",
            "last_delivery_at": 0,
            "created": 0,
            "updated": 0
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}

{
    "url": "https://example.com/motordesk/webhook",
    "events": [
        "vehicle.created",
        "vehicle.updated",
        "vehicle.sold"
    ],
    "scopes": [
        "vehicles:read"
    ],
    "description": "Inventory sync"
}

{
    "success": true,
    "data": {
        "id": 0,
        "url": "",
        "description": "",
        "events": "",
        "scopes": [
            ""
        ],
        "status": "active",
        "secret_hint": "",
        "secret": "",
        "failure_count": 0,
        "last_status": "delivered",
        "last_delivery_at": 0,
        "created": 0,
        "updated": 0
    }
}

{
    "success": true,
    "data": {
        "id": 0,
        "url": "",
        "description": "",
        "events": "",
        "scopes": [
            ""
        ],
        "status": "active",
        "secret_hint": "",
        "secret": "",
        "failure_count": 0,
        "last_status": "delivered",
        "last_delivery_at": 0,
        "created": 0,
        "updated": 0
    }
}

{
    "url": "",
    "events": "",
    "status": "active",
    "description": ""
}

{
    "success": true,
    "data": {
        "id": 0,
        "url": "",
        "description": "",
        "events": "",
        "scopes": [
            ""
        ],
        "status": "active",
        "secret_hint": "",
        "secret": "",
        "failure_count": 0,
        "last_status": "delivered",
        "last_delivery_at": 0,
        "created": 0,
        "updated": 0
    }
}

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Ping

{
    "success": true,
    "data": {
        "queued": false,
        "delivery_id": 0,
        "message": ""
    }
}

Secret

{
    "success": true,
    "data": {
        "id": 0,
        "url": "",
        "description": "",
        "events": "",
        "scopes": [
            ""
        ],
        "status": "active",
        "secret_hint": "",
        "secret": "",
        "failure_count": 0,
        "last_status": "delivered",
        "last_delivery_at": 0,
        "created": 0,
        "updated": 0
    }
}

Deliveries

{
    "success": true,
    "data": [
        {
            "id": 0,
            "event": "",
            "event_id": "",
            "status": "pending",
            "attempts": 0,
            "response_code": 0,
            "response_ms": 0,
            "response_body": "",
            "next_attempt_at": 0,
            "created": 0,
            "delivered_at": 0
        }
    ]
}

{
    "success": true,
    "data": {
        "id": 0,
        "event": "",
        "event_id": "",
        "status": "pending",
        "attempts": 0,
        "response_code": 0,
        "response_ms": 0,
        "response_body": "",
        "next_attempt_at": 0,
        "created": 0,
        "delivered_at": 0
    }
}