Webhooks for Marketplace Apps

When building a Samsara App, there's no global webhook handler for all customers. Instead, you must create dedicated webhook endpoints for each customer using the Create a webhook endpoint with the customer's OAuth access token. This enables your app to receive real-time notifications—like driver and address updates, form submissions, or route updates—for each customer’s data.

Before you begin

Authentication
- All requests must include a valid API token in the request header. For marketplace apps, this TOKEN is the customer's OAuth access token: Authentication: Bearer <TOKEN>
Scopes
- Read Webhooks under “Setup & Administration” is required for listing and retrieving existing webhooks.
- Write Webhooks under “Setup & Administration” is required for creating, updating, or deleting webhooks.

1. List webhook endpoints

Use the List all webhooks endpoint to retrieve webhook endpoints that belong to a specific organization. Note, if your marketplace application is installed by multiple customers, this endpoint will only return the webhook endpoints for the organization related to the access token used to authenticate the request.

Example Request

curl -X GET 'https://api.samsara.com/webhooks' \
--header "Authentication: Bearer <TOKEN>"

Example Response

{
  "data": [
    {
      "customHeaders": [
        {
          "key": "format",
          "value": "xcmol-532"
        }
      ],
      "eventTypes": [
        "AddressCreated",
        "AddressUpdated",
        "DriverCreated"
      ],
      "id": "23918",
      "name": "Webhook-123",
      "secretKey": "11121-31231-1231212",
      "url": "https://www.webhook-123.com/webhook/listener",
      "version": "2018-01-01"
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

Note: secretKey is auto-generated by Samsara and can be used to verify the authenticity of the webhook payload on your server. See the Webhooks 2.0 Reference for webhook signature verification examples.

2. Retrieve a webhook endpoint

Use the Retrieve a webhook endpoint to retrieve the details of a single webhook by its id.

Example Request

curl -X GET 'https://api.samsara.com/webhooks/23918' \
--header "Authentication: Bearer <TOKEN>"

Example Response

{
  "customHeaders": [
    {
      "key": "format",
      "value": "xcmol-532"
    }
  ],
  "eventTypes": [
    "AddressCreated",
    "DriverCreated"
  ],
  "id": "23918",
  "name": "Webhook-123",
  "secretKey": "11121-31231-1231212",
  "url": "https://www.webhook-123.com/webhook/listener",
  "version": "2018-01-01"
}

3. Create a webhook endpoint

Use the Create a webhook endpoint to create a new webhook. A webhook is defined by at least a name and a url using https. Optionally, you can add customHeaders or specify which eventTypes you want this webhook to receive.

Note: See the Webhooks 2.0 Reference for a list of supported eventTypes.

Example Request

curl -X POST 'https://api.samsara.com/webhooks' \
--header "Authentication: Bearer <TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "Webhook-123",
  "url": "https://www.webhook-123.com/webhook/listener",
  "version": "2018-01-01",
  "customHeaders": [
    {
      "key": "x-TMS-Account-ID",
      "value": "98765"
    }
  ],
  "eventTypes": ["AddressCreated", "AddressUpdated", "DriverCreated", "DriverUpdated"]
}'

Example Response

{
    "id": "5148647976029837",
    "name": "Webhook-123",
    "url": "https://www.webhook-123.com/webhook/listener",
    "version": "2018-01-01",
    "secretKey": "pBNU8ZU26pFccodoBbxKkhm4SpI=",
    "customHeaders": [
        {
            "key": "x-TMS-Account-ID",
            "value": "98765"
        }
    ],
    "eventTypes": [
        "DriverCreated",
        "DriverUpdated",
        "AddressCreated",
        "AddressUpdated"
    ]
}

4. Update a webhook endpoint

Use the Update a webhook endpoint to update an existing webhook. This endpoint follows the JSON merge patch standard, meaning any field specified in the request body replaces the existing field on the server. For arrays, the entire array is replaced.

Example Request

Suppose we only need to update the name and customHeaders:

curl -X PATCH 'https://api.samsara.com/webhooks/5148647976029837' \
--header "Authentication: Bearer <TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "New Webhook Name",
  "eventTypes": [
      "DriverCreated",
      "DriverUpdated",
      "AddressCreated",
      "AddressUpdated",
      "AddressDeleted"
  ]
}'

Example Response

{
    "id": "5148647976029837",
    "name": "Webhook-123",
    "url": "https://www.webhook-123.com/webhook/listener",
    "version": "2018-01-01",
    "secretKey": "pBNU8ZU26pFccodoBbxKkhm4SpI=",
    "customHeaders": [
        {
            "key": "x-TMS-Account-ID",
            "value": "98765"
        }
    ],
    "eventTypes": [
        "DriverCreated",
        "DriverUpdated",
        "AddressCreated",
        "AddressUpdated",
        "AddressDeleted"
    ]
}

5. Delete a webhook

Use the Delete a webhook endpoint to remove a webhook. Once deleted, Samsara will no longer send events to this URL.

Example Request

curl -X DELETE 'https://api.samsara.com/webhooks/5148647976029837' \
--header "Authentication: Bearer <TOKEN>"

If successful, the response returns an empty body with a 204 No Content status.

Using webhooks with alert configurations

Once you have created a webhook endpoint, you can use it as an action for an Alert Configuration so that when certain triggers are met (e.g. speeding, harsh events, HOS violations), Samsara will send a notification to your webhook URL.

Use the Create alert configurations. endpoint to bind your newly created webhook to an alert.

Example Request

curl --location 'https://api.samsara.com/alerts/configurations' \
--header 'Content-Type: application/json' \
--header 'Authorization: <TOKEN>' \
--data '{
  "actions": [
    {
      "actionTypeId": 4,
      "actionParams": {
        "webhooks": {
          "webhookIds": [
            "2319097551794453"
          ],
          "payloadType": "enriched"
        }
      }
    }
  ],
  "isEnabled": true,
  "name": "Engine On",
  "scope": {
    "all": true
  },
  "triggers": [
    {
      "triggerTypeId": 1021,
      "triggerParams": {
        "engineOn": {
          "minDurationMilliseconds": 6000
        }
      }
    }
  ]
}'

Example Response

{
  "name": "Engine On",
  "isEnabled": true,
  "triggers": [
    {
      "triggerTypeId": 1021,
      "triggerParams": {
        "engineOn": {
          "minDurationMilliseconds": 6000
        }
      }
    }
  ],
  "actions": [
    {
      "actionTypeId": 4,
      "actionParams": {
        "webhooks": {
          "payloadType": "enriched",
          "webhookIds": [
            "2319097551794453"
          ]
        }
      }
    }
  ],
  "scope": {
    "all": true
  },
  "id": "a4dd0eb1-1d51-4dee-aad9-0fa8e6e70da9",
  "createdAtTime": "2025-02-12T18:58:04Z",
  "lastModifiedAtTime": "2025-02-12T18:58:04Z"
}

How It Works

Create the Webhook
First, create (or reuse) a webhook endpoint using the Create a Webhook endpoint. Copy the resulting id from the response.
Set Up the Alert
In the Create Alert Configuration body, specify:
- A trigger (e.g., speeding) by including the relevant triggerTypeId and any required parameters.
- An action using actionTypeId=4 for Webhook, and place the webhook’s id in actionParams.webhooks.webhookIds.
Receive Alerts
Whenever the specified trigger condition (in the above example, vehicle speed over 70 mph) is met for the vehicles in your scope, Samsara will send an Alert Webhook payload to your configured url (the one you set in the webhook). You can then process, log, or display the alert in your TMS integration.

By leveraging both webhook endpoints and alert configurations, you can build powerful real-time monitoring capabilities into your Marketplace App—ensuring you are instantly notified when critical events occur.

Application lifecycle

Installation when a customer completes the OAuth flow and connects their Samsara account to your application, Create a new webhook endpoint.
Off boarding if a customer disconnects their OAuth connection to Samsara, delete the webhook.