Plan your integration

Add webhook notifications

1. Types of Webhooks

Smartcar currently supports two kinds of webhooks:

Schedule-Based Webhooks: You subscribe your application to notifications based on a periodic schedule. These webhooks are available for our standard API endpoints found in the API Reference (any endpoint that is not unique to a specific brand). Schedule-based webhooks are only available on paid plans. See our website for more details.
Event-Based Webhooks: You subscribe your application to notifications based on a pre-specified condition. We currently offer event-based webhooks for: start charge, stop charge, and charge completion. Event-based webhooks are only available to select customers on enterprise plans. Contact our sales team to learn more.

In order to use webhooks for automating notifications for your web or mobile application, you must:

Log in or create an account at dashboard.smartcar.com and enroll in a paid plan.
Navigate to “Webhooks” in the dashboard navigation bar and click “Create your first webhook” or add subsequent webhooks to your existing list.
Add a name and callback URI for your webhook. You will have the option of selecting between schedule-based webhooks and event-based webhooks.

Note: event-based webhooks are only available for select customers on enterprise plans.

2. Utilizing Schedule-Based Webhooks

If you select “Scheduled” from the drop-down, you will see an expanded list of actions to complete. Add a scheduled webhook in Smartcar's Developer Dashboard.

Select the frequency of notifications. They can be hourly, daily, weekly, or monthly. Once you select a frequency, you will also need to select the interval for when data should be sent. (e.g. if you select hourly, you will need to choose if you want data to be sent every 1 hour, 2 hours, 3 hours, etc.) The recommendation for how often to schedule notifications varies based on use case, but the general consensus is that anywhere between every 24 hours to 7 days is more than sufficient for most use cases.
Select which endpoints you would like to see covered by your webhook subscription. You can find out more about endpoint permissions in the API reference. Note: it is possible that a specific vehicle model/year is not supported in a specific region. Check Brand Compatibility to ensure the endpoints you are interested in are mostly or fully covered.
Select whether you would like to use metric or imperial units for all the result fields.

You can now add your webhook!

3a. Utilizing Event-Based Webhooks

If you select “Event Based” from the drop-down, you will be prompted to select which endpoint events to read. Add an event-based webhook in Smartcar's Developer Dashboard.

3b. Current limitations with Event-Based Webhooks

Today, there are a couple of limitations with event-based webhooks:

Webhooks are limited to charge started, stopped, and complete endpoints from the API reference.
Event-based webhooks are only available on Tesla, Ford, and Toyota (RAV4 Prime only).
1. Tesla and Ford have support in all regions covered by Smartcar.
2. Toyota is currently supported in the US and Canada.
3. Ford start charge requires some extra validation upfront from the vehicle owner. They will be prompted through the FordPass app. (MyFord Mobile has been sunset by Ford)

We are currently working to support more makes for event-based webhooks.

4. Webhook Verification

Once you add your webhook, in order to activate it, your code should generate a signature containing your management token and the bolded challenge string. It should follow the following:

// POST <callback-uri>

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

Your webhook should now be active. If you have problems with this step, contact customer support for further assistance.

5. Resulting Outputs

Now that your webhook is active, you should start seeing notifications in the same format as specified in the API reference!

For an example of schedule-based and event-based webhook outputs, see below:

// Schedule-based webhook for fuel:

{
   "version": "2.0",
   "webhookId": "6f9c7e43-2278-4a9b-b273-cdacab9ed83c",
   "eventName": "schedule",
   "mode": "live",
   "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"
         }
      ]
   }
}


//Event-based webhook for charge completion:

{
   "version": "2.0",
   "webhookId": "abde94ff-d57d-43b9-8d09-6020db2d977a",
   "eventName": "eventBased",
   "mode": "live",
   "payload":
   {
      "eventId": "1713eab1-eebc-4b4e-9433-0f2a488851c2",
      "vehicleId": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
      "eventType": "CHARGING_COMPLETED",
      "eventTime": "2022-04-06T01:4 8:22.845Z"
   }
}