Webhooks

Creating Webhooks

You can create webhooks in order to be notified of alerts that occur in your Samsara account. This is particularly useful if you are looking to build integrations that relay a special alert event, such as when a vehicle arrives at a given location, or if your container temperature exceeds a given amount. For a complete list of all alerts that occur in Samsara, please refer to this Alerts Summary page.

Webhooks can be viewed and created via the Samsara dashboard.  Navigate to the Settings tab and click on Advanced > Webhooks. Click on (+ Add Webhook) to create a webhook. Each webhook must have a name and route to a https URL.

Once a webhook has been created, individual alerts can be configured to send to a given webhook URL. To do so, navigate to the Alerts tab to create a new alert or configure an existing alert. 

Verifying Webhook Signatures

Samsara uses webhook signatures in order to indicate that a payload has been sent by Samsara. Webhook payloads are signed by a HMAC-SHA256 encryption, which can be found in the "X-Samsara-Signature" header.

To verify that the payload is coming from us, you can compute the signature from your end and verify it matches the signature in the header. Below is some Python-based pseudocode to verify that your computed signature matches the one in the header of the payload.

import hashlib
import hmac
import base64

timestamp = header["X-Samsara-Timestamp"]
plaintext_signature = "v1:%s:%s" % (timestamp, body)
secret = base64.b64decode("CZkHS7GSYgwMp03CjtR26G9lPqw=")
signature = base64.b64encode(hmac.new(secret, plaintext_signature,digestmod=hashlib.sha256).digest())
assert(signature==header["X-Samsara-Signature"])

Static Webhook IP addresses

Samsara will post to your webhook URL using one of the following IP addresses. We strongly encourage you to verify all webhook signatures using the signature algorithm above, but if you would also like to restrict updates by IP address, then please consult the list on the Webhooks page in your dashboard. The list is subject to change, so please check back periodically.

Responding to Webhook Events

You should acknowledge the receipt of a webhook request with a 2xx response code. If a webhook is not acknowledged, then Samsara will continue to retry in an exponential backoff fashion.