Webhooks for Marketplace Apps

Create and manage per-customer webhook endpoints from your Marketplace app using OAuth access tokens and the Webhooks API.

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

1. 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: Authorization: Bearer YOUR_API_TOKEN.

2. 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 that 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 "Authorization: Bearer YOUR_API_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
  }
}

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 "Authorization: Bearer YOUR_API_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.

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

Example Request

curl -X POST 'https://api.samsara.com/webhooks' \
  --header "Authorization: Bearer YOUR_API_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 eventTypes:

curl -X PATCH 'https://api.samsara.com/webhooks/5148647976029837' \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "New Webhook Name",
    "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 "Authorization: Bearer YOUR_API_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: Bearer YOUR_API_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 }
        }
      }
    ]
  }'

How It Works

1. Create the webhook

   First, create (or reuse) a webhook endpoint using the Create a Webhook endpoint. Copy the resulting id from the response.

2. 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.
3. 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. 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

1. Installation

   When a customer completes the OAuth flow and connects their Samsara account to your application, create a new webhook endpoint.

2. Off-boarding

   If a customer disconnects their OAuth connection to Samsara, delete the webhook.