# Smartcar Webhooks

## When to Use This Skill

* How do I receive Smartcar webhooks?
* How do I verify the Smartcar `SC-Signature` header?
* How do I respond to the Smartcar `VERIFY` challenge so my webhook activates?
* How do I handle `VEHICLE_STATE` and `VEHICLE_ERROR` events?
* Why is my Smartcar webhook signature verification failing?

## Verification (core)

Smartcar signs every webhook with a hex-encoded HMAC-SHA256 of the raw
request body, keyed with your Application Management Token (AMT, from the
Smartcar Dashboard), in the `SC-Signature` header. On setup Smartcar also POSTs
a one-time `VERIFY` event whose `data.challenge` you must hash with the same AMT
and echo back within 15 seconds — otherwise the webhook never activates. This is
Smartcar's own scheme, not the Standard Webhooks spec.

The official SDKs expose two helpers: `hashChallenge`/`hash_challenge` (hex HMAC
of any string) and `verifyPayload`/`verify_payload` (compares the header against
the body's HMAC).

Node (Express, Next.js):

```javascript
const smartcar = require('smartcar');
const AMT = process.env.SMARTCAR_MANAGEMENT_TOKEN;

// 1. VERIFY handshake — echo the hashed challenge so the webhook activates
if (event.eventType === 'VERIFY') {
  const hmac = smartcar.hashChallenge(AMT, event.data.challenge); // hex string
  return res.status(200).json({ challenge: hmac });
}

// 2. Data events — verify SC-Signature (hex HMAC-SHA256 of the raw body).
//    The Node SDK re-serializes the parsed body internally, so pass the object.
if (!smartcar.verifyPayload(AMT, req.headers['sc-signature'], event)) {
  return res.status(401).send('Invalid signature');
}

```

Python (FastAPI) — the SDK hashes the raw body string you pass in:

```python
import smartcar
amt = os.environ["SMARTCAR_MANAGEMENT_TOKEN"]

if event["eventType"] == "VERIFY":
    return {"challenge": smartcar.hash_challenge(amt, event["data"]["challenge"])}

if not smartcar.verify_payload(amt, request.headers["sc-signature"], raw_body):
    raise HTTPException(status_code=401, detail="Invalid signature")

```

> For complete handlers with route wiring, VERIFY handling, event dispatch, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/smartcar-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/smartcar-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/smartcar-webhooks/examples/fastapi/)

## Common Event Types

| `eventType` | Triggered When | Common Use Cases |
| --- | --- | --- |
| `VERIFY` | Webhook is created or re-verified from the Dashboard | Echo the hashed `data.challenge` to activate the webhook |
| `VEHICLE_STATE` | A monitored signal changes (e.g. battery state of charge, odometer) | Sync vehicle data, trigger alerts, update dashboards |
| `VEHICLE_ERROR` | Smartcar fails to retrieve a subscribed signal | Surface connection issues; a follow-up event with `state: "RESOLVED"` fires on recovery |

Legacy v2 `scheduled` / `eventBased` webhooks are deprecated — use the event
types above.

> For the full event reference, see [Smartcar Webhook Events](https://smartcar.com/docs/integrations/webhooks/overview).

## Environment Variables

```bash
SMARTCAR_MANAGEMENT_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # Application Management Token from the Dashboard

```

The Application Management Token is the only secret needed to verify
payloads and answer the VERIFY challenge — it keys every HMAC.

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 smartcar --path /webhooks/smartcar

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/smartcar-webhooks/references/overview.md) - Smartcar webhook concepts, event types, payload structure
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/smartcar-webhooks/references/setup.md) - Dashboard configuration, Application Management Token, subscribing vehicles
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/smartcar-webhooks/references/verification.md) - SC-Signature verification, VERIFY challenge, manual HMAC, gotchas