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
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 was fired
`data`	The event-specific payload (see per-event schemas below)

Per-Event Data Schemas

`setup.complete`

{
  "website_url": "https://baydodge.net",
  "provider": "DealerInspire",
  "configuration_id": 42,
  "vehicle_counts": { "new": 85, "used": 120 },
  "status": "active"
}

`setup.failed`

{
  "website_url": "https://baydodge.net",
  "error": "Unable to detect inventory provider"
}

`import.complete`

{
  "website_url": "https://baydodge.net",
  "stats": {
    "total_received": 205,
    "new": 3,
    "updated": 198,
    "removed": 4,
    "unchanged": 0
  }
}

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

The data field contains the vehicle object directly (not wrapped in a {"vehicle": {...}} envelope):

{
  "vin": "5GAEVBKSXTJ122446",
  "year": 2026,
  "make": "Buick",
  "model": "Enclave",
  "condition": "New",
  "price": 49430
}

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.

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. You may receive the same event more than once — always make your handler idempotent.
Retry schedule. Failed deliveries are retried up to 3 total attempts with exponential backoff (approximately 4 seconds, then 8 seconds between retries). Only server errors (5xx) trigger retries — client errors (4xx) are not retried.
Auto-disable. After reaching the max_failures threshold (default 10, configurable when creating the webhook) of consecutive failures, the webhook subscription is automatically deactivated. Use the reactivate endpoint to re-enable it.
Timeout. Your endpoint must respond within 10 seconds. Longer responses are treated as failures. Do the minimum work synchronously (queue the event for background processing) and return a 2xx immediately.
Ordering. Events within a single dealership are generally ordered, but cross-dealership ordering is not guaranteed.

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

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

​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

Inspecting deliveries

Managing webhooks

Related