@smartcar/webhooks

TypeScript SDK for processing Smartcar webhook payloads.

Installation

npm install @smartcar/webhooks

Basic Usage

1. Parse and Verify Webhook Payload

import { parseEnvelope, verifySignature, hashChallenge } from '@smartcar/webhooks';
import type { WebhookDataPayload } from '@smartcar/webhooks';

// Express.js webhook handler example
app.post('/webhooks', (req, res) => {
  const signature = req.headers['SC-Signature'] as string;
  const rawPayload = req.body;
  const webhookSecret = process.env.WEBHOOK_SECRET!;
  
  // 1. Verify the webhook signature (recommended for security)
  if (!verifySignature(webhookSecret, rawPayload, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // 2. Parse the webhook payload
  const payload: WebhookDataPayload = parseEnvelope(rawPayload);
  
  // 3. Handle different event types
  handleWebhookEvent(payload, webhookSecret, res);
});

2. Handle Different Event Types

function handleWebhookEvent(payload: WebhookDataPayload, secret: string, res: any) {
  // Check if this is a webhook verification event
  if (payload.eventType === 'VERIFY') {
    const challenge = payload.data.challenge;
    if (typeof challenge === 'string') {
      const hash = hashChallenge(secret, challenge);
      return res.json({ challenge: hash });
    }
    return res.status(400).json({ error: 'Invalid challenge' });
  }
  
  // Handle vehicle state events
  if (payload.eventType === 'VEHICLE_STATE') {
    handleVehicleStateEvent(payload);
  }
  
  // Handle vehicle error events  
  if (payload.eventType === 'VEHICLE_ERROR') {
    handleVehicleErrorEvent(payload);
  }
  
  res.status(204).end();
}

API Reference

Functions

parseEnvelope(buffer: Buffer): WebhookDataPayload

Parses a raw webhook payload buffer into a structured object.

verifySignature(secret: string, payload: Buffer, signature: string): boolean

Verifies the webhook signature for security.

hashChallenge(secret: string, challenge: string): string

Creates a hash response for webhook verification challenges.

Types

The package exports TypeScript types for all webhook payload structures:

import type { 
  WebhookDataPayload,
  VehicleStateEvent,
  VehicleErrorEvent,
  WebhookVerifyEvent
} from '@smartcar/webhooks';

Security Best Practices

1. Always verify signatures - Use verifySignature() to ensure webhooks are from Smartcar
2. Use HTTPS - Only accept webhooks over secure connections
3. Validate timestamps - Reject old webhook payloads to prevent replay attacks
4. Use raw body parser - Express must receive the raw buffer for signature verification

Integration with @smartcar/signals

For type-safe signal processing, combine with the @smartcar/signals package:

import { getSignalByCode } from '@smartcar/signals';
import type { TractionBatteryStateOfCharge } from '@smartcar/signals';

// Note: Webhook payload signals may need transformation 
// to match the signal types structure
const batterySignal = getSignalByCode<TractionBatteryStateOfCharge>(
  transformedSignals, 
  'tractionbattery-stateofcharge'
);

License

MIT