Webhooks

Webhooks let AutosnapAI push events to your server instead of making you poll. When a vehicle is added, updated, removed, or when an inventory import completes, we send a signed HTTP POST to a URL you configure.

When to use webhooks

Real-time inventory sync — keep your database in lockstep with AutosnapAI without polling
Marketing automation — trigger an email when a “Great Deal” vehicle hits inventory
Data warehouse pipelines — stream events into BigQuery, Snowflake, or similar
Alerting — notify your team when an important dealer’s inventory stops updating

Event types

Website Inventory Events

Event	Fires when
`vehicle.created`	A new vehicle appears in scraped inventory
`vehicle.updated`	A vehicle’s fields change (price drop, description update, photos added)
`vehicle.removed`	A vehicle is removed from active inventory (sold, transferred, or delisted)
`import.complete`	A scheduled or on-demand inventory import finishes for a dealership
`setup.complete`	A dealer setup job finishes successfully
`setup.failed`	A dealer setup job fails

Dealer Health Check Events

Event	Fires when
`dealer.config.auto_updated`	A dealership’s scraper configuration was automatically repaired (e.g. changed site ID)
`dealer.provider.changed`	A dealership switched to a different website provider

IMS Feed Events

Event	Fires when
`ims.import.complete`	An IMS feed file was successfully imported (new/updated/removed vehicle counts in payload)
`ims.feed.stale`	An IMS feed file has not been updated within the configured staleness threshold
`ims.vehicle.created`	A new vehicle appears in an IMS feed import
`ims.vehicle.updated`	An existing IMS vehicle’s data changes
`ims.vehicle.removed`	A vehicle is no longer present in the IMS feed (marked inactive)

Website inventory events and IMS feed events are independent. If a dealership has both a website scraper and an IMS feed, you’ll receive events from both sources. Use the event prefix (ims.* vs no prefix) to distinguish the source.

Creating a webhook

You provide a secret (minimum 16 characters) when creating the webhook. This secret is used to sign every delivery so you can verify it came from AutosnapAI.

curl -X POST "https://api.autosnap.com/v1/webhooks" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "'$AUTOSNAP_API_KEY'",
    "url": "https://yourapp.com/webhooks/autosnap",
    "event_types": ["vehicle.created", "vehicle.updated", "vehicle.removed", "import.complete", "ims.vehicle.created", "ims.vehicle.updated", "ims.vehicle.removed", "ims.import.complete"],
    "secret": "your_secret_at_least_16_chars",
    "dealership_id": "dlr_8cfc0b00a98b"
  }'

Response

{
  "success": true,
  "created": [
    { "webhook_id": 42, "event_type": "vehicle.created" },
    { "webhook_id": 43, "event_type": "vehicle.updated" },
    { "webhook_id": 44, "event_type": "vehicle.removed" },
    { "webhook_id": 45, "event_type": "import.complete" },
    { "webhook_id": 46, "event_type": "ims.vehicle.created" },
    { "webhook_id": 47, "event_type": "ims.vehicle.updated" },
    { "webhook_id": 48, "event_type": "ims.vehicle.removed" },
    { "webhook_id": 49, "event_type": "ims.import.complete" }
  ],
  "skipped": [],
  "url": "https://yourapp.com/webhooks/autosnap",
  "dealership_id": "dlr_8cfc0b00a98b"
}

The API creates one webhook record per event type. If you subscribe to 4 event types, the response created array will have 4 entries, each with its own webhook_id.

Webhook delivery format

Every webhook delivery is an HTTP POST with these headers:

POST /webhooks/autosnap HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-Autosnap-Signature: a3f2c8b4e9d1f7a2b5c8d3e6f9a1b4c7d0e3f6a9...
X-Autosnap-Event: vehicle.created
X-Autosnap-Event-Id: 6f1c2a9e-3b7d-4c55-9a0e-2d8f41b7c913
User-Agent: AutoSnap-Webhook/1.0

The payload structure:

{
  "event": "vehicle.created",
  "dealership_id": "dlr_8cfc0b00a98b",
  "timestamp": "2026-04-13T14:32:19.123456+00:00",
  "data": {
    "vin": "5GAEVBKSXTJ122446",
    "make": "Buick",
    "model": "Enclave",
    "year": 2026,
    "price": 49430
    /* ... full vehicle object ... */
  }
}

Field	Description
`event`	The event type (e.g. `vehicle.created`)
`dealership_id`	Public dealership ID (`dlr_xxxx`)
`timestamp`	ISO 8601 timestamp of when the event happened. It is the same on every retry of that event.
`data`	The event-specific payload (see per-event schemas below)

Per-Event Data Schemas

`setup.complete`

{
  "website_url": "baydodge.net",
  "provider": "DealerInspire",
  "configuration_id": 42,
  "vehicle_counts": { "new": 85, "used": 120, "total": 205 },
  "status": "active",
  "setup_id": "setup_6420ad759b71",
  "requested_url": "https://www.baydodge.net"
}

website_url is the dealership’s canonical host (scheme, www and path removed) — the same identifier the rest of the API uses. setup_id is the ID the setup endpoint returned with its 202 and requested_url is the URL exactly as you submitted it; use either (or the envelope’s dealership_id) to map the event back to your own request.

`setup.failed`

{
  "website_url": "baydodge.net",
  "error": "Unable to detect inventory provider",
  "failure_mode": "CMS_NOT_DETECTED",
  "setup_id": "setup_6420ad759b71",
  "requested_url": "https://www.baydodge.net"
}

The envelope’s dealership_id is null on setup.failed when the failure happened before a dealership record existed — setup_id and requested_url still identify the request.

`import.complete`

{
  "website_url": "dutchmillernissanofashland.com",
  "stats": {
    "dealership_name": "Dutch Miller Nissan of Ashland",
    "total_received": 275,
    "inserted": 0,
    "updated": 275,
    "changed": 55,
    "unchanged": 220,
    "skipped": 0,
    "errors": 0,
    "vehicles_deactivated": 0,
    "active_vehicle_count": 275,
    "duration_seconds": 1.8
  }
}

website_url is the dealership’s canonical host. inserted = vehicles new to this import, updated = vehicles seen again (of which changed had a field change and unchanged did not), vehicles_deactivated = vehicles removed by this import, active_vehicle_count = active vehicles after it.

`vehicle.created` / `vehicle.updated` / `vehicle.removed`

The data field is the vehicle object directly (not wrapped in a {"vehicle": {...}} envelope). It is the same vehicle object POST /v1/inventory/fetch returns for that car, with the same fields, prices, price breakdown and photos, plus dealership_id and dealer_name.

Event	Sent when
`vehicle.created`	A vehicle appears in the dealership’s inventory as returned by `/v1/inventory/fetch`
`vehicle.updated`	Any field of that vehicle changes, including `final_price`, `price_components`, fees, discounts, photos and description. Fields that change on every inventory refresh without the car changing (`updated_at`, `scraped_date`, `last_seen`, `age_days`) do not send an update by themselves.
`vehicle.removed`	The vehicle is no longer returned by `/v1/inventory/fetch` (sold, transferred, or delisted). `data` is the last known vehicle object, with `dealership_active: false` (only `id`, `vin` and `dealership_active` if the vehicle record no longer exists).

Vehicle events are checked after each inventory refresh for the dealership. A new dealership’s first inventory import sends vehicle.created for each vehicle it adds. If you subscribe to a dealership whose inventory we already have, events describe changes from then on: take the starting inventory from /v1/inventory/fetch.

Events are scoped per dealership. Each event’s top-level envelope includes the dealership_id the event belongs to. When a dealer group shares used-inventory across multiple rooftops, the same VIN may generate parallel events from each participating dealership — each event is legitimate for its own dealership scope. Deduplicate on (dealership_id, vin) if you need a unified view. See Concepts: Vehicles — Core identifiers for details.

`ims.import.complete`

Both events fire for every IMS feed import. If you subscribe to both, you will receive two webhooks per import with the same payload. Subscribe to one or the other, not both.

{
  "feed_config_id": 1,
  "file_name": "MP14015.csv",
  "vehicle_count": 381,
  "new_count": 3,
  "updated_count": 378,
  "removed_count": 2
}

`ims.feed.stale`

{
  "feed_config_id": 1,
  "dealership_id": "dlr_8cfc0b00a98b",
  "provider": "vauto",
  "staleness_hours": 53.2,
  "threshold_hours": 48
}

`ims.vehicle.created` / `ims.vehicle.updated` / `ims.vehicle.removed`

{
  "vin": "1GCHSCEA7L1214921",
  "stock_number": "M1382",
  "year": 2020,
  "make": "Chevrolet",
  "model": "Colorado 2WD",
  "condition": "Used",
  "price": 18999
}

For vehicle events (vehicle.created, vehicle.updated, vehicle.removed), the data field contains the vehicle object directly — it is NOT wrapped in a {"vehicle": {...}} envelope.

X-Autosnap-Event-Id is a unique ID for each event delivered to your webhook. If we retry a delivery, the retry has the same ID and the exact same body. Use it to skip events you have already processed.

Signature verification

Always verify the signature on every webhook before acting on the payload. Anyone can POST to a public URL — signatures prove the request actually came from AutosnapAI. The X-Autosnap-Signature header contains an HMAC-SHA256 hex digest of the raw request body, computed using the secret you provided when creating the webhook:

HMAC-SHA256(secret, raw_request_body)

import hmac, hashlib

def verify_webhook(secret: str, signature_header: str, raw_body: bytes) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require('crypto');

function verifyWebhook(secret, signatureHeader, rawBody) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Retry and delivery semantics

At-least-once delivery. Every event is saved before we send it, so it is not lost if your endpoint is down. You may receive the same event more than once: use X-Autosnap-Event-Id to skip duplicates.
Retry schedule. Server errors (5xx), timeouts, connection errors, 408 and 429 are retried. Other client errors (4xx) mean your endpoint rejected the event, and are not retried. The gaps between attempts grow: 30 seconds, 2 minutes, 5 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, 3 hours, then every 4 hours. We keep retrying for 24 hours from when the event happened.
Endpoint down. If several deliveries to your endpoint fail in a row, we pause and resend the waiting events once it recovers, instead of sending each one into a failing endpoint.
Auto-disable. A webhook is deactivated only after your endpoint has been unreachable or failing (server errors, timeouts, connection errors, 408, 429) continuously for 24 hours with no successful delivery. A 4xx rejection of an individual event does not count toward this. Use the reactivate endpoint to turn it back on. Events from those 24 hours that could not be delivered are not resent; use POST /v1/inventory/fetch to resync.
Timeout. Your endpoint must respond within 10 seconds. Longer responses are treated as failures and retried. Do the minimum work synchronously (queue the event for background processing) and return a 2xx immediately.
Ordering. Events for the same vehicle sent to the same URL are always delivered in order (vehicle.created before vehicle.updated before vehicle.removed), including across retries, even when you subscribe to each event type separately. Events for different vehicles or dealerships, or to different URLs, may arrive in any order.

Test and production keys

A webhook belongs to the environment of the API key that created it. Create your Pre-Prod webhooks with a test key and your Production webhooks with a production key, and each environment only receives its own events:

Event	Production webhooks	Test webhooks
`setup.complete` / `setup.failed`	Setups requested with a production key	Setups requested with a test key
Vehicle and import events (`vehicle.*`, `import.complete`)	Every dealership on your account (or the one in `dealership_id`)	Only the dealership given in `dealership_id`

There is one inventory per dealership, so a test webhook needs a dealership_id to receive vehicle or import events. Create one test webhook per dealership you want to test with. Without a dealership_id, a test webhook receives setup events only. A test key lists and manages only test webhooks. It can’t delete or change webhooks or dealerships created with a production key; those requests return 403. All dealerships on your account can be read with either key, so you don’t need to set them up again for testing.

Inspecting deliveries

curl "https://api.autosnap.com/v1/webhooks/{webhook_id}/deliveries?api_key=$AUTOSNAP_API_KEY&limit=50"

Returns delivery attempts (default 50, max 100) with status codes, response times, and error messages. Use the limit query parameter to control how many results are returned. Useful for debugging when events aren’t reaching your server.

Managing webhooks

# List all webhooks
curl "https://api.autosnap.com/v1/webhooks?api_key=$AUTOSNAP_API_KEY"

# Reactivate a disabled webhook (resets failure count)
curl -X PATCH "https://api.autosnap.com/v1/webhooks/{webhook_id}/reactivate?api_key=$AUTOSNAP_API_KEY"

# Reactivate ALL disabled webhooks
curl -X PATCH "https://api.autosnap.com/v1/webhooks/reactivate-all?api_key=$AUTOSNAP_API_KEY"

# Delete a webhook
curl -X DELETE "https://api.autosnap.com/v1/webhooks/{webhook_id}?api_key=$AUTOSNAP_API_KEY"

Handling webhooks

Full end-to-end guide with receiver code and deployment tips

Webhook endpoints

Full webhook API reference

Get Started

Concepts

Guides

Support

When to use webhooks

Event types

Website Inventory Events

Dealer Health Check Events

IMS Feed Events

Creating a webhook

Webhook delivery format

Per-Event Data Schemas

`setup.complete`

`setup.failed`

`import.complete`

`vehicle.created` / `vehicle.updated` / `vehicle.removed`

`ims.import.complete`

`ims.feed.stale`

`ims.vehicle.created` / `ims.vehicle.updated` / `ims.vehicle.removed`

Signature verification

Retry and delivery semantics

Test and production keys

Inspecting deliveries

Managing webhooks

Handling webhooks

Webhook endpoints

​When to use webhooks

​Event types

​Website Inventory Events

​Dealer Health Check Events

​IMS Feed Events

​Creating a webhook

​Webhook delivery format

​Per-Event Data Schemas

​setup.complete

​setup.failed

​import.complete

​vehicle.created / vehicle.updated / vehicle.removed

​ims.import.complete

​ims.feed.stale

​ims.vehicle.created / ims.vehicle.updated / ims.vehicle.removed

​Signature verification

​Retry and delivery semantics

​Test and production keys

​Inspecting deliveries

​Managing webhooks

​Related

Handling webhooks

Webhook endpoints

When to use webhooks

Event types

Website Inventory Events

Dealer Health Check Events

IMS Feed Events

Creating a webhook

Webhook delivery format

Per-Event Data Schemas

`setup.complete`

`setup.failed`

`import.complete`

`vehicle.created` / `vehicle.updated` / `vehicle.removed`

`ims.import.complete`

`ims.feed.stale`

`ims.vehicle.created` / `ims.vehicle.updated` / `ims.vehicle.removed`

Signature verification

Retry and delivery semantics

Test and production keys

Inspecting deliveries

Managing webhooks

Related