Scheduled Webhooks
Scheduled webhooks make it incredibly easy to receive vehicle data on a cadence of your choosing. You can set up a webhook for any Smartcar endpoint that allows you to read data from a vehicle.
This tutorial is split into four steps:
- Creating your webhook
- Verifying your callback URI
- Confirmation with a test payload
- 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
- Navigate to the Webhooks section of Dashboard and hit + Add Webhook.
- Next, name your webhook, enter in your callback URI, and select Scheduled as the type.
- 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
- 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.
See the callback verification section on our API Reference for insructions on how to format your response.
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 scheduled
.
The mode
field will reflect the type of vehicle you’ve subscribed - either live
, test
or simulated
.
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 receiving your initial ACCESS_TOKEN
from the auth code exchange step for Connect,
you’ll first want to hit the All Vehicles endpoint to fetch the Smartcar
vehicle_id
s of the authorized vehicles.
With your ACCESS_TOKEN
and WEBHOOK_ID
you can hit the Subscribe
endpoint for each vehicle_id
to start receiving data.
FAQs
When will I receive my first scheduled webhook?
When will I receive my first scheduled webhook?
Data will post to the endpoint depending on your selected cadence. For example:
- if a car is subscribed to an hourly interval webhook at 15:45 UTC, you’ll get start to get data after 16:00UTC.
- if a car is subscribed to a monthly interval, we’ll process the webhooks at 00:00UTC for the selected day.
Can I use an Event Based webhook to receive scheduled webhooks?
Can I use an Event Based webhook to receive scheduled webhooks?
No, you’ll need to set up a webhook for each webhook type.
Can I use the same callback URI for my webhooks?
Can I use the same callback URI for my webhooks?
Yes! You can distinguish between webhook types based on the eventName
field - scheduled
or eventBased
.
I've stopped receiving events
I've stopped receiving events
- Once a webhook is configured, we’ll begin sending events to your Callback URI on the cadence that you’ve chosen. We’ll expect a 2xx response to each. In the event that we don’t receive a 2xx response, we’ll retry 5 times over the next 10 minutes. If we continue not to receive a successful response, we’ll automatically disable your webhook.
- Check that your server didn’t experience down time for more than 10 minutes recently resulting in 2XX responses not being sent back to Smartcar.
- If you haven’t made any major changes to your callback URI, commonly our request payload may have hit the request size limit for you server.
Will I always receive payloads in line with my configured cadence?
Will I always receive payloads in line with my configured cadence?
While we aim for 1 to 5 minutes after your selected cadence, the delivery time largely depends on the number of vehicles you have subscribed as well as the average OEM latency. Smartcar will try to fulfill requests for your webhook within 15 minutes of the scheduled time. If we were unable to fulfill a request during that time, we’ll try again over the course of subsequent 15 minute intervals and post them to your webhook.