Push Vehicle Events in Real Time With Webhooks

Polling an API on a timer is wasteful and slow: you either hammer the endpoint or you learn about a change hours late. VIN Doc webhooks invert the relationship: we call your endpoint the moment a vehicle event lands. This guide covers the integration end to end, from subscription to signature verification to the unglamorous but essential work of surviving retries.

Subscribe to an event type

From the dashboard you register a callback URL and select the event types you care about: title changes, new damage records, recall notices, or odometer anomalies. Each subscription is scoped to an environment and signed with its own secret, so a sandbox subscription and a production one never share a key.

• Subscribe only to events you will act on
• Use separate endpoints for sandbox and production
• Version your callback path so you can migrate safely

Subscribing to everything feels safe but is the opposite. Every event you do not act on is noise in your logs and load on your handler. Pick the events that change a decision and ignore the rest until they earn their place.

Understand the delivery payload

A delivery is a small JSON envelope describing what changed and which vehicle it concerns, not a full report. The payload carries an event ID, an event type, the affected VIN, and a timestamp; if you need the complete picture you fetch the vehicle by VIN after acknowledging.

{
  "event_id": "evt_9f3",
  "type": "title.changed",
  "vin": "1HGCM82633A004352",
  "ts": "2026-06-15T08:14:00Z"
}

Keeping the envelope thin means deliveries stay fast and your handler stays simple. Treat the webhook as a notification, not as the source of truth.

Verify the signature

Every delivery includes an HMAC signature header computed over the raw request body. Recompute it with your subscription secret and reject anything that does not match. This is the single most important step: an unverified webhook endpoint is an open door for anyone who guesses your URL.

expected = hmac_sha256(secret, raw_body)
if not constant_time_equals(expected, header_signature):
    return 401

Compare in constant time and verify against the raw bytes, not a re-serialized object, because re-serialization can subtly change the body and break the check.

Acknowledge fast, process later

Return a 2xx within a couple of seconds and do the heavy work asynchronously. Push the payload onto a queue and let a worker enrich your records. If you block on downstream calls inside the handler, you risk timeouts and unnecessary retries that multiply your load exactly when you least want it.

• Respond 2xx immediately, then enqueue
• Make handlers idempotent for duplicate deliveries
• Store the event ID to detect replays

Handle retries and backfill

We retry failed deliveries with exponential backoff for up to 24 hours. Design handlers to tolerate the same event arriving more than once: dedupe on the event ID so a redelivery updates nothing it has already applied. For the rare gap, the events endpoint lets you list everything in a time range and reconcile, so a brief outage on your side never means lost data.

Choose the right granularity

A common mistake is treating every event type as equally urgent. A title change usually warrants an immediate reaction; a routine record update might be fine to batch and process on a schedule. Map each event type to the response it actually deserves, and route them accordingly. Some belong on a fast path that pages a human, others belong in a nightly digest. Mixing the two means either drowning your operators in low-value notifications or burying a critical title change in the noise. The subscription model lets you split these cleanly, so use that flexibility rather than funneling everything through one handler that has to guess at urgency.

Operate with confidence

A healthy webhook integration is observable: watch your acknowledgment latency, your queue depth, and your delivery failure rate, and the dashboard shows you the full retry history of every delivery from our side. You can validate all of this against the sandbox before going live, and the free trial runs two days for €3.99 then €49.99/month, auto-renewing and cancelable anytime, so there is no reason to test event handling in production first. Done right, webhooks turn vehicle history from something you ask about into something that tells you when it changes.