How Webhooks are Sent
Webhook payloads are sent as HTTP requests to theVehicle data callback URI
you defined when you set up the webhook.
The HTTP request body consists of a JSON payload. Webhook payloads will be one of VEHICLE_STATE
or VEHICLE_ERROR
as defined in Response Payloads.
Optionally, you may configure a separate Vehicle error callback URI
for VEHICLE_ERROR
payloads. If this is not defined, all payloads will be sent to the primary URI.
Verifying Your Receiver Endpoint
Before you can receive vehicle data, Smartcar will send a verification payload to yourVehicle data callback URI
to validate that your receiver is reachable and responding appropriately.
Please see Callback URI Verification for details on how to correctly respond to this request.
Responding to Webhook Deliveries
Smartcar expects your webhook receiver to return an HTTP200
response within 15 seconds of each delivery. Any other status code, or responses that exceed this 15-second timeout, are treated as errors and the delivery will be marked unsuccessful.
Smartcar will attempt to re-deliver unsuccessful requests up to three times, with exponential backoff. If a timely 200
response code is not received for all attempts, the payload is dropped. Future deliveries will still be attempted as long as the webhook is active.
As a best practice, you should decouple webhook receiving and payload processing. If your receiver does not respond because of a processing issue, Smartcar will consider the payload undelivered and will send it again. Persist the payload first, then run any signal processing logic as a separate step.
Verifying Payloads
You may want to verify payloads you receive are legitimate and complete. Smartcar cryptographically signs each payload using a signature that can only be decoded with your Application Management Token. See Payload verification for details.Networking Considerations
- Webhook receivers must be accessible from the public internet so Smartcar can resolve your receiver URI.
- Receiver URIs must use HTTPS with a valid SSL certificate.
- Internal corporate network addresses or custom SSL certificates are not supported.
- Smartcar sends webhook payloads from public IPv4 addresses, which may change over time. Be careful when defining firewall rules.