This tutorial is split into four steps:

1. Creating your webhook
2. Verifying your callback URI
3. Confirmation with a test payload
4. Subscribing your first vehicle

​

Prerequisites

For this tutorial it is recommended to have the following in place:

• To receive webhooks you’ll need to set up a callback URI on your server.
• To subscribe a vehicle you’ll want to have Connect set up.

​

Creating your first webhook

1. Navigate to the Webhooks section of Dashboard and hit + Add Webhook.
2. Next, name your webhook, enter in your callback URI, and select Scheduled as the type.
   
3. After selecting the type, you’ll need to:
   • set how often you want receive data
   • select which endpoints you want to receive data from
   • select the units you want to receive data
   
4. Once you’re happy with the configuration, hit Add Webhook and move on to verifying your callback URI.

​

Verifying your callback URI

After adding your webhook, you’ll be prompted to verify it. After hitting Verify this webhook Smartcar will post a challenge request to your callback URI to ensure we’re sending payloads to the correct place.

This is a one time event and will be in the following format where the eventName will be verify

    {
        "version": "2.0",
        "webhookId": "<uuid>",
        "eventName": "verify",
        "payload": { "challenge": "<random-string>" }
    }

Upon receiving the request, your server will need respond to the challenge by hashing payload.challenge with your APPLICATION_MANAGEMENT_TOKEN to create a SHA-256 based HMAC.

Return the hex-encoded hash as the value for challenge in your response body with a 2XX status code.

{
    "status" : 204,
    "headers" : {
        "Content-Type": "application/json"
    },
    "body" : {
        "challenge" : "{HMAC}"
    }
}

See the callback verification section on our API Reference for more information.

​

Confirmation with a test payload

Once verified you can send a test payload to your callback URI. Payloads from vehicles will have eventName set to schedule.

{
  "version": "2.0",
  "webhookId": "6f9c7e43-2278-4a9b-b273-cdacab9ed83c",
  "eventName": "schedule",
  "mode": "test",
  "payload": {
    "vehicles": [
      {
        "vehicleId": "1a9fdd59-b65e-4bf1-8264-5448812eac83",
        "requestId": "6c22cd5c-34df-48ae-ad90-b324170629be",
        "data": [
          {
            "path": "/",
            "code": 200,
            "body": {
              "id": "1a9fdd59-b65e-4bf1-8264-5448812eac83",
              "make": "BMW",
              "model": "i3 94 (+ REX)",
              "year": 2017
            },
            "headers": {}
          },
          {
            "path": "/fuel",
            "code": 200,
            "body": {
              "range": 44.12,
              "percentRemaining": 0.57,
              "amountRemaining": 1.32
            },
            "headers": {
              "sc-data-age": "2020-05-11T23:44:31.000Z",
              "sc-unit-system": "imperial"
            }
          },
          {
            "path": "/vin",
            "code": 200,
            "body": {
              "vin": "WBY1Z8C54HV550878"
            },
            "headers": {}
          }
        ],
        "timestamp": "2020-05-13T22:00:01.288Z"
      }
    ]
  }
}

​

Subscribing your first vehicle

Now you’ve got your webhook set up, you can subscribe vehicles to start getting data at your desired frequency. If you haven’t done so already, please set up the Connect for your application.

After receivng your initial ACCESS_TOKEN from the auth code excahnge step for Connect, you’ll first want to hit the All Vehicles endpoint to fetch the Smartcar vehicle_ids of the authorized vehicles.

curl "https://api.smartcar.com/v2.0/vehicles" \
-H "Authorization: Bearer {token}" \
-X "GET"

With your ACCESS_TOKEN and WEBHOOK_ID you can hit the Subscribe endpoint for each vehicle_id to start receiving data.

curl "https://api.smartcar.com/v2.0/vehicles/{vehicleId}/webhooks/{webhookId}" \
-H "Authorization: Bearer {token}" \
-X "POST"

​

FAQs