Skip to main content
Learn how to build a basic webhook endpoint that receives, parses, and acknowledges Smartcar webhook deliveries.
Want to skip the manual setup?Deploy a production-ready webhook receiver to AWS in minutes with our Webhook Receiver Recipe. It includes complete serverless infrastructure (Lambda + API Gateway + SQS), built-in signature verification, automatic error handling, and TypeScript type safety.Perfect for: New implementations, AWS environments, or teams wanting to deploy quickly without infrastructure overhead.

​
Basic Requirements

Your webhook endpoint must meet these requirements:
  • Accept POST requests - Smartcar sends all webhooks as HTTP POST requests
  • Return 2xx status code - Any status code from 200-299 acknowledges successful receipt
  • Use HTTPS - Your endpoint must use HTTPS with a valid SSL certificate
  • Respond within 15 seconds - Return a status code before the timeout window
  • Publicly accessible - Your endpoint must be accessible from the public internet

​
Quick Start Examples

Here are minimal webhook receivers that handle the required VERIFY event and acknowledge all other events: 
const express = require('express');
const smartcar = require('smartcar');
const app = express();

app.use(express.json());

app.post('/webhooks/smartcar', (req, res) => {
  const { eventType, data } = req.body;
  
  // Handle VERIFY event (required)
  if (eventType === 'VERIFY') {
    const hmac = smartcar.hashChallenge(
      process.env.SMARTCAR_MANAGEMENT_TOKEN,
      data.challenge
    );
    return res.status(200).json({ challenge: hmac });
  }
  
  // Log other events
  console.log('Received webhook:', eventType);
  
  // Acknowledge receipt
  res.status(200).json({ status: 'received' });
  
  // Process asynchronously (recommended)
  // processWebhook(req.body);
});

app.listen(3000);
VERIFY event required - Your endpoint must successfully respond to the VERIFY event before Smartcar delivers any vehicle data. See Callback Verification for detailed instructions and troubleshooting.
Best practice: Return 200 immediately and process the webhook asynchronously. See Architecture Best Practices for the queue-based pattern.
Any 2xx works: You can return 200, 201, 202, 204, or any other 2xx status code. Smartcar treats all 2xx responses as successful delivery.

​
What Happens After Verification

After your endpoint successfully responds to the VERIFY event, Smartcar will begin delivering VEHICLE_STATE and VEHICLE_ERROR events for subscribed vehicles.
Understanding payloads: For detailed payload structure, field definitions, and event-specific schemas, see the Event Reference Overview.

​
Next Steps

Complete the VERIFY challenge first - Your endpoint must successfully respond to the VERIFY event before Smartcar delivers any vehicle data. See Handling the VERIFY Event above.
Once your endpoint is verified and receiving webhooks, continue implementing your integration with these guides:

Payload Verification

Verify all payloads are authentic using the SC-Signature header

Event Reference

Understand VEHICLE_STATE, VEHICLE_ERROR, and VERIFY event structures

Best Practices

Implement idempotency, queuing, monitoring, and error handling

Delivery Behavior

Learn about retry policies, timeouts, and ordering guarantees

​
FAQ

Your endpoint must successfully respond to the VERIFY event before Smartcar delivers any VEHICLE_STATE or VEHICLE_ERROR events. Check the Dashboard to confirm your webhook shows “Verified” status.
Use ngrok or similar to expose your local server:
ngrok http 3000
Then use the ngrok URL in Dashboard as your callback URI. Note that you will have to re-verify the webhook after changing the callback URI.
Always verify the SC-Signature header to ensure payloads are authentic. See Payload Verification.
No. Return 200 immediately and process asynchronously using a queue. This prevents timeouts and retry storms. See Architecture Best Practices.