VERIFY Event

A one-time event sent when you first create a webhook to verify that Smartcar can successfully deliver payloads to your callback URL.

Required Before Data DeliveryYour endpoint must successfully respond to the VERIFY event before Smartcar will deliver any VEHICLE_STATE or VEHICLE_ERROR events. This confirms your endpoint is configured correctly and ready to receive webhooks.

When This Event Fires

The VERIFY event fires once when you:

Create a new webhook in the Smartcar Dashboard
Update the callback URL of an existing webhook
Click “Verify this webhook” in the Dashboard

Payload Structure

{
  "eventId": "52f6e0bb-1369-45da-a61c-9e67d092d6db",
  "eventType": "VERIFY",
  "data": {
    "challenge": "3a5c8f72-e6d9-4b1a-9f2e-8c7d6a5b4e3f"
  },
  "meta": {
    "version": "4.0",
    "webhookId": "5a8e5e38-1e12-4011-a36d-56f120053f9e",
    "webhookName": "Example Webhook",
    "deliveryId": "5d569643-3a47-4cd1-a3ec-db5fc1f6f03b",
    "deliveredAt": 1761896351529
  }
}

{
  "version": "2.0",
  "webhookId": "5a8e5e38-1e12-4011-a36d-56f120053f9e",
  "eventName": "verify",
  "payload": { 
    "challenge": "3a5c8f72-e6d9-4b1a-9f2e-8c7d6a5b4e3f"
  }
}

Payload Fields

string

required

Unique identifier for this verification event.

string

required

Always "VERIFY" for this event type.

object

required

Container for the challenge.

Show data object

string

required

Random string that must be hashed with your Application Management Token and returned in your response.

object

required

Webhook delivery metadata. See Event Reference Overview for the complete meta object schema.

Required Response

Your endpoint must respond with:

Status code: 200 OK
Content-Type header: application/json
Response body: JSON object with the HMAC-SHA256 hash

Response Body

{
  "challenge": "a3f5c8e9d2b4a1f6e8c7d9a5b3e1f2c4d6a8b9c1e3f5a7b9c2d4e6f8a1b3c5d7"
}

Generate the HMAC

Create an HMAC-SHA256 hash of the challenge string using your Application Management Token as the secret key, then hex-encode the result:

import hmac
import hashlib

signature = hmac.new(
    application_management_token.encode(),
    challenge.encode(),
    hashlib.sha256,
).hexdigest()

# Return in response body
return {"challenge": signature}, 200

const crypto = require('crypto');

const hmac = crypto
  .createHmac('sha256', application_management_token)
  .update(challenge)
  .digest('hex');

// Return in response body
res.status(200).json({ challenge: hmac });

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(application_management_token.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] raw = mac.doFinal(challenge.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder();
for (byte b : raw) {
    sb.append(String.format("%02x", b));
}
String hmac = sb.toString();

// Return in response body
return ResponseEntity.ok(Map.of("challenge", hmac));

require 'openssl'

hmac = OpenSSL::HMAC.hexdigest('SHA256', application_management_token, challenge)

# Return in response body
{ challenge: hmac }

Complete Handler Example

Here’s a complete webhook handler that responds to the VERIFY event:

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/smartcar', (req, res) => {
  const { eventType, data } = req.body;
  
  if (eventType === 'VERIFY') {
    // Generate HMAC challenge response
    const hmac = crypto
      .createHmac('sha256', process.env.SMARTCAR_MANAGEMENT_TOKEN)
      .update(data.challenge)
      .digest('hex');
    
    return res.status(200).json({ challenge: hmac });
  }
  
  // Handle other event types...
  res.status(200).json({ status: 'received' });
});

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)

@app.post('/webhooks/smartcar')
def webhook_handler():
    payload = request.get_json()
    event_type = payload.get('eventType')
    
    if event_type == 'VERIFY':
        # Generate HMAC challenge response
        signature = hmac.new(
            os.environ['SMARTCAR_MANAGEMENT_TOKEN'].encode(),
            payload['data']['challenge'].encode(),
            hashlib.sha256,
        ).hexdigest()
        
        return jsonify({"challenge": signature}), 200
    
    # Handle other event types...
    return jsonify({"status": "received"}), 200

@RestController
public class WebhookController {
    
    @Value("${smartcar.management.token}")
    private String managementToken;
    
    @PostMapping("/webhooks/smartcar")
    public ResponseEntity<?> handleWebhook(@RequestBody Map<String, Object> payload) throws Exception {
        String eventType = (String) payload.get("eventType");
        
        if ("VERIFY".equals(eventType)) {
            // Generate HMAC challenge response
            Map<String, Object> data = (Map<String, Object>) payload.get("data");
            String challenge = (String) data.get("challenge");
            
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(managementToken.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            byte[] raw = mac.doFinal(challenge.getBytes(StandardCharsets.UTF_8));
            StringBuilder sb = new StringBuilder();
            for (byte b : raw) {
                sb.append(String.format("%02x", b));
            }
            String hmac = sb.toString();
            
            return ResponseEntity.ok(Map.of("challenge", hmac));
        }
        
        // Handle other event types...
        return ResponseEntity.ok(Map.of("status", "received"));
    }
}

require 'sinatra'
require 'json'
require 'openssl'

post '/webhooks/smartcar' do
  payload = JSON.parse(request.body.read)
  event_type = payload['eventType']
  
  if event_type == 'VERIFY'
    # Generate HMAC challenge response
    hmac = OpenSSL::HMAC.hexdigest(
      'SHA256',
      ENV['SMARTCAR_MANAGEMENT_TOKEN'],
      payload['data']['challenge']
    )
    
    status 200
    content_type :json
    return { challenge: hmac }.to_json
  end
  
  # Handle other event types...
  status 200
  content_type :json
  { status: 'received' }.to_json
end

Troubleshooting

Verification fails in Dashboard

Common causes:

Wrong Application Management Token used
HMAC not hex-encoded
Response body doesn’t match { "challenge": "..." } format
Endpoint returns non-200 status code
Response takes longer than 15 seconds

Solution: Use the Dashboard’s verification modal to see the expected challenge and response. Compare your implementation against the provided code snippets.

How do I test VERIFY locally?

Use ngrok or similar to expose your local server:

ngrok http 3000

Then use the ngrok URL as your callback URI in the Dashboard. The Dashboard will send a real VERIFY event to your local endpoint.

Can I re-verify my webhook?

Yes! You can click “Verify this webhook” in the Dashboard at any time to send a new VERIFY event to your endpoint.

Do I need to handle VERIFY in production?

Yes, your production webhook endpoint should always handle the VERIFY event type, even after initial verification. This allows you to re-verify from the Dashboard if needed.

Timeout RequirementYour endpoint must respond to the VERIFY event within 15 seconds. If verification times out, Smartcar will not activate the webhook.

Next Steps

After successfully responding to the VERIFY event, your webhook is activated and will begin receiving vehicle data.

VEHICLE_STATE Event

Learn about signal data deliveries

VEHICLE_ERROR Event

Handle error notifications

Callback Verification Guide

Complete step-by-step implementation

Receiving Webhooks

Build a complete webhook handler

Introduction

Authorization

Connections

Webhooks

Vehicle Data

Vehicle Commands

Vehicle Settings

Interactions

Compatibility

API 2.0 Reference (Legacy)

Vehicle Commands (Legacy)

Management API (Legacy)

Compatibility API (Legacy)

When This Event Fires

Payload Structure

Payload Fields

Required Response

Generate the HMAC

Complete Handler Example

Troubleshooting

Next Steps

VEHICLE_STATE Event

VEHICLE_ERROR Event

Callback Verification Guide

Receiving Webhooks