A collection of TypeScript SDKs for handling Smartcar webhooks and vehicle signals in backend applications.
This monorepo contains the following packages:
- @smartcar/webhooks - SDK for handling Smartcar webhook payloads and signature verification
- @smartcar/signals - SDK for parsing and working with vehicle signal data
- example - Example implementation showing how to use both packages together (not published to npm)
npm install @smartcar/webhooks @smartcar/signalsimport express from "express";
import { verifySignature, hashChallenge, parseEnvelope } from "@smartcar/webhooks";
import { getSignalByCode, type ChargeAmperage } from "@smartcar/signals";
const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;
app.post("/webhooks", (req, res) => {
// Parse the webhook payload
const payload = parseEnvelope(req.body);
// Handle webhook verification challenge
if (payload.eventType === "VERIFY") {
const hash = hashChallenge(WEBHOOK_SECRET, payload.data.challenge);
return res.json({ challenge: hash });
}
// Handle vehicle state updates
if (payload.eventType === "VEHICLE_STATE") {
const signals = payload.data.signals;
// Extract specific signal with type safety
const amperage = getSignalByCode<ChargeAmperage>(signals, 'charge-amperage');
if (amperage?.status.value === "SUCCESS") {
console.log(`Charge amperage: ${amperage.body.value} ${amperage.body.unit}`);
}
}
res.status(200).end();
});- Signature Verification: Verify webhook payload authenticity using HMAC-SHA256
- Challenge Hashing: Generate challenge responses for webhook verification
- Payload Parsing: Parse webhook envelopes with proper TypeScript types
- Type Safety: Fully typed webhook payload structures
- Type-Safe Signal Access: Extract specific signals with full TypeScript support
- Auto-Generated Types: All signal types generated from OpenAPI specifications
- Signal Utilities: Helper functions for working with signal arrays
- Comprehensive Coverage: Support for all Smartcar vehicle signals
- Node.js 18+
- npm 8+
# Clone the repository
git clone https://github.com/smartcar/typescript-backend-sdks.git
cd typescript-backend-sdks
# Install dependencies
npm install
# Generate types from OpenAPI specs
npm run gen
# Build all packages
npm run buildnpm run gen- Generate TypeScript types from OpenAPI specificationsnpm run build- Build all packagesnpm run test- Run tests for all packagesnpm run clean- Clean build artifactsnpm run release- Release all packages (automated in CI)npm run release:dry-run- Test release process without publishing
Each package has its own scripts:
# In packages/signals or packages/webhooks
npm run build # Build the package
npm run test # Run package tests
npm run release # Release the package
npm run clean # Clean build artifactsThis project uses semantic-release for automated versioning and publishing. Releases are triggered automatically when commits are pushed to the master branch.
We follow Conventional Commits:
feat(signals): add new feature→ minor version bumpfix(webhooks): fix bug→ patch version bumpfeat(signals)!: breaking change→ major version bump
See CONTRIBUTING.md for detailed commit guidelines.
This project uses Buddy for continuous integration and deployment:
- CI Pipeline: Runs tests on all branches
- CD Pipeline: Automatically releases packages from
masterbranch - Semantic Release: Automated versioning based on conventional commits
For setup instructions, see Buddy Setup Guide.
npm run clean- Clean generated files and build artifacts
├── packages/
│ ├── webhooks/ # Webhook handling SDK
│ ├── signals/ # Vehicle signals SDK
│ └── example/ # Example implementation
├── schema.yml # Webhook payload OpenAPI spec
├── signal-open-api.yml # Vehicle signals OpenAPI spec
└── package.json # Workspace configuration
The SDK supports the following webhook event types:
- VERIFY - Webhook endpoint verification challenge
- VEHICLE_STATE - Vehicle state updates with signal data
- VEHICLE_ERROR - Vehicle error notifications
All vehicle signals are fully typed based on the OpenAPI specification. Common signal types include:
ChargeAmperage- Electric vehicle charging amperageBatteryLevel- Vehicle battery percentageLocation- Vehicle GPS coordinatesOdometer- Vehicle mileage- And many more...
Both SDKs provide comprehensive TypeScript support:
// Signals are strongly typed
const amperage: ChargeAmperage | undefined = getSignalByCode<ChargeAmperage>(
signals,
'charge-amperage'
);
// Webhook payloads have proper typing
const payload: WebhookDataPayload = parseEnvelope(buffer);Run the test suite:
npm testCheck out the example package for a complete implementation showing:
- Express.js server setup
- Webhook signature verification
- Signal parsing and processing
- Error handling
- Environment configuration
We welcome contributions! Please read our contributing guidelines for details on:
- Commit message format (we use Conventional Commits)
- Development workflow
- Testing requirements
- Release process
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes following our commit convention
- Add tests for your changes
- Run the test suite:
npm test - Test the release process:
npm run release:dry-run - Commit your changes:
git commit -am 'feat(signals): add new feature' - Push to the branch:
git push origin feature/my-feature - Submit a pull request
This project is licensed under the ISC License.