Skip to main content

​
How Webhooks are Sent

Webhook payloads are sent as HTTP requests to the Vehicle 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 your Vehicle 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 HTTP 200 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.