Samsara Webhooks API
The Webhooks API from Samsara — 2 operation(s) for webhooks.
OpenAPI Specification
openapi: 3.0.1
info:
description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
title: Samsara Webhooks API
version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Webhooks
paths:
/webhooks:
get:
description: "List all webhooks belonging to a specific org.\n\n <b>Rate limit:</b> 5 requests/sec (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Read Webhooks** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>\n \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team."
operationId: listWebhooks
parameters:
- description: ' A filter on the data based on this comma-separated list of webhook IDs. Example: `ids=49412323223,49412329928`'
in: query
name: ids
schema:
type: string
- description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
in: query
name: limit
schema:
default: 512
maximum: 512
minimum: 1
type: integer
- description: ' If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.'
in: query
name: after
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksResponseBody'
description: OK response.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksUnauthorizedErrorResponseBody'
description: Unauthorized response.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksNotFoundErrorResponseBody'
description: Not Found response.
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksMethodNotAllowedErrorResponseBody'
description: Method Not Allowed response.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksTooManyRequestsErrorResponseBody'
description: Too Many Requests response.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksInternalServerErrorResponseBody'
description: Internal Server Error response.
'501':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksNotImplementedErrorResponseBody'
description: Not Implemented response.
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksBadGatewayErrorResponseBody'
description: Bad Gateway response.
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksServiceUnavailableErrorResponseBody'
description: Service Unavailable response.
'504':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksGatewayTimeoutErrorResponseBody'
description: Gateway Timeout response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListWebhooksBadRequestErrorResponseBody'
description: Bad Request response.
summary: List All Webhooks Belonging to a Specific Org.
tags:
- Webhooks
post:
description: "Create a webhook\n\n <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Write Webhooks** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>\n \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team."
operationId: postWebhooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksResponseBody'
description: OK response.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksUnauthorizedErrorResponseBody'
description: Unauthorized response.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksNotFoundErrorResponseBody'
description: Not Found response.
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksMethodNotAllowedErrorResponseBody'
description: Method Not Allowed response.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksTooManyRequestsErrorResponseBody'
description: Too Many Requests response.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksInternalServerErrorResponseBody'
description: Internal Server Error response.
'501':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksNotImplementedErrorResponseBody'
description: Not Implemented response.
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksBadGatewayErrorResponseBody'
description: Bad Gateway response.
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksServiceUnavailableErrorResponseBody'
description: Service Unavailable response.
'504':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksGatewayTimeoutErrorResponseBody'
description: Gateway Timeout response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPostWebhooksBadRequestErrorResponseBody'
description: Bad Request response.
summary: Create a Webhook
tags:
- Webhooks
x-codegen-request-body-name: PostWebhooksRequestBody
/webhooks/{id}:
delete:
description: "Delete a webhook with the given ID.\n\n <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Write Webhooks** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>\n \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team."
operationId: deleteWebhook
parameters:
- description: Unique identifier for the webhook to delete.
in: path
name: id
required: true
schema:
type: string
responses:
'204':
content: {}
description: No Content response.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookUnauthorizedErrorResponseBody'
description: Unauthorized response.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookNotFoundErrorResponseBody'
description: Not Found response.
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookMethodNotAllowedErrorResponseBody'
description: Method Not Allowed response.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookTooManyRequestsErrorResponseBody'
description: Too Many Requests response.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookInternalServerErrorResponseBody'
description: Internal Server Error response.
'501':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookNotImplementedErrorResponseBody'
description: Not Implemented response.
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookBadGatewayErrorResponseBody'
description: Bad Gateway response.
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookServiceUnavailableErrorResponseBody'
description: Service Unavailable response.
'504':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookGatewayTimeoutErrorResponseBody'
description: Gateway Timeout response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksDeleteWebhookBadRequestErrorResponseBody'
description: Bad Request response.
summary: Delete a Webhook With the Given ID
tags:
- Webhooks
get:
description: "Retrieve a webhook with given ID.\n\n <b>Rate limit:</b> 5 requests/sec (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Read Webhooks** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>\n \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team."
operationId: getWebhook
parameters:
- description: ID of the webhook. This is the Samsara-specified ID.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookResponseBody'
description: OK response.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookUnauthorizedErrorResponseBody'
description: Unauthorized response.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookNotFoundErrorResponseBody'
description: Not Found response.
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookMethodNotAllowedErrorResponseBody'
description: Method Not Allowed response.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookTooManyRequestsErrorResponseBody'
description: Too Many Requests response.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookInternalServerErrorResponseBody'
description: Internal Server Error response.
'501':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookNotImplementedErrorResponseBody'
description: Not Implemented response.
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookBadGatewayErrorResponseBody'
description: Bad Gateway response.
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookServiceUnavailableErrorResponseBody'
description: Service Unavailable response.
'504':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookGatewayTimeoutErrorResponseBody'
description: Gateway Timeout response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksGetWebhookBadRequestErrorResponseBody'
description: Bad Request response.
summary: Retrieve a Webhook With Given ID
tags:
- Webhooks
patch:
description: "Update a specific webhook's information. **Note** this implementation of patch uses [the JSON merge patch](https://tools.ietf.org/html/rfc7396) proposed standard.\n This means that any fields included in the patch request will _overwrite_ fields which exist on the target resource.\n For arrays, this means any array included in the request will _replace_ the array that exists at the specified path, it will not _add_ to the existing array\n\n <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Write Webhooks** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>\n \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team."
operationId: patchWebhook
parameters:
- description: Unique identifier for the webhook to update.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookResponseBody'
description: OK response.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookUnauthorizedErrorResponseBody'
description: Unauthorized response.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookNotFoundErrorResponseBody'
description: Not Found response.
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookMethodNotAllowedErrorResponseBody'
description: Method Not Allowed response.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookTooManyRequestsErrorResponseBody'
description: Too Many Requests response.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookInternalServerErrorResponseBody'
description: Internal Server Error response.
'501':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookNotImplementedErrorResponseBody'
description: Not Implemented response.
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookBadGatewayErrorResponseBody'
description: Bad Gateway response.
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookServiceUnavailableErrorResponseBody'
description: Service Unavailable response.
'504':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookGatewayTimeoutErrorResponseBody'
description: Gateway Timeout response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksPatchWebhookBadRequestErrorResponseBody'
description: Bad Request response.
summary: Update a Specific Webhook's Information.
tags:
- Webhooks
x-codegen-request-body-name: PatchWebhookRequestBody
components:
schemas:
WebhooksPatchWebhookResponseBody:
properties:
customHeaders:
description: The list of custom headers that users can include with their request
items:
$ref: '#/components/schemas/CustomHeadersObjectResponseBody'
maxItems: 5
type: array
eventTypes:
description: The list of event types associated with a particular webhook.
example:
- AddressCreated
- AddressCreated
- AddressCreated
items:
description: 'This is the name of the event type. Valid values: `AddressCreated`, `AddressDeleted`, `AddressUpdated`, `AlertIncident`, `AlertObjectEvent`, `DocumentSubmitted`, `DriverCreated`, `DriverUpdated`, `DvirSubmitted`, `EngineFaultOff`, `EngineFaultOn`, `FormSubmitted`, `GatewayUnplugged`, `GeofenceEntry`, `GeofenceExit`, `IssueCreated`, `PredictiveMaintenanceAlert`, `RouteStopArrival`, `RouteStopDeparture`, `RouteStopResequence`, `SevereSpeedingEnded`, `SevereSpeedingStarted`, `VehicleCreated`, `VehicleUpdated`'
enum:
- AddressCreated
- AddressDeleted
- AddressUpdated
- AlertIncident
- AlertObjectEvent
- DocumentSubmitted
- DriverCreated
- DriverUpdated
- DvirSubmitted
- EngineFaultOff
- EngineFaultOn
- FormSubmitted
- GatewayUnplugged
- GeofenceEntry
- GeofenceExit
- IssueCreated
- PredictiveMaintenanceAlert
- RouteStopArrival
- RouteStopDeparture
- RouteStopResequence
- SevereSpeedingEnded
- SevereSpeedingStarted
- VehicleCreated
- VehicleUpdated
example: AddressCreated
type: string
type: array
id:
description: The ID of the webhook. This will appear in both Samsaras cloud dashboard and the API. This is the id of the webhook. This is system generated.
example: '23918'
type: string
name:
description: The name of the webhook. This will appear in both Samsaras cloud dashboard and the API. It can be set or updated through the Samsara Dashboard or through the API at any time.
example: Webhook-123
type: string
secretKey:
description: The secret key of the webhook. This will appear in both Samsaras cloud dashboard and the API.
example: 11121-31231-1231212
type: string
url:
description: The url of the webhook. This will appear in both Samsaras cloud dashboard and the API. It can be set or updated through the Samsara Dashboard or through the API at any time.
example: https://www.webhook-123.com/webhook/listener
type: string
version:
description: 'The version of the webhook. Valid values: `2018-01-01`, `2021-06-09`'
enum:
- '2018-01-01'
- '2021-06-09'
example: '2018-01-01'
type: string
required:
- id
- name
- secretKey
- url
- version
type: object
WebhooksDeleteWebhookNotImplementedErrorResponseBody:
description: Requested endpoint is not yet implemented
properties:
message:
description: Message of error
example: Not implemented.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPostWebhooksTooManyRequestsErrorResponseBody:
description: Too many requests
properties:
message:
description: Message of error
example: Exceeded rate limit.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPostWebhooksBadRequestErrorResponseBody:
description: Bad Request parameters
properties:
message:
description: Message of error
example: Invalid value for parameter.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPatchWebhookNotFoundErrorResponseBody:
description: Resource not found
properties:
message:
description: Message of error
example: Object not found.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksListWebhooksBadGatewayErrorResponseBody:
description: Bad Gateway
properties:
message:
description: Message of error
example: 'rpc error: code = Unknown desc = connection refused'
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPatchWebhookServiceUnavailableErrorResponseBody:
description: Service unavailable
properties:
message:
description: Message of error
example: context deadline exceeded
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPatchWebhookGatewayTimeoutErrorResponseBody:
description: Gateway timeout
properties:
message:
description: Message of error
example: context deadline exceeded
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksListWebhooksTooManyRequestsErrorResponseBody:
description: Too many requests
properties:
message:
description: Message of error
example: Exceeded rate limit.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
CustomHeadersObjectRequestBody:
description: This is the object that stores the key and the value of the custom headers.
properties:
key:
description: The alphanumeric key of the custom header.
example: format
maxLength: 100
type: string
value:
description: The value of the custom header. The default maximum length of the value is 100 characters.
example: xcmol-532
type: string
required:
- key
- value
type: object
WebhooksGetWebhookNotImplementedErrorResponseBody:
description: Requested endpoint is not yet implemented
properties:
message:
description: Message of error
example: Not implemented.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPostWebhooksBadGatewayErrorResponseBody:
description: Bad Gateway
properties:
message:
description: Message of error
example: 'rpc error: code = Unknown desc = connection refused'
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksGetWebhookGatewayTimeoutErrorResponseBody:
description: Gateway timeout
properties:
message:
description: Message of error
example: context deadline exceeded
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
GoaPaginationResponseResponseBody:
description: Pagination parameters.
properties:
endCursor:
description: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.
example: MjkY
type: string
hasNextPage:
description: True if there are more pages of results immediately available after this endCursor.
example: true
type: boolean
required:
- endCursor
- hasNextPage
type: object
WebhooksGetWebhookTooManyRequestsErrorResponseBody:
description: Too many requests
properties:
message:
description: Message of error
example: Exceeded rate limit.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksListWebhooksNotFoundErrorResponseBody:
description: Resource not found
properties:
message:
description: Message of error
example: Object not found.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPatchWebhookMethodNotAllowedErrorResponseBody:
description: Method not allowed
properties:
message:
description: Message of error
example: DELETE not allowed on /endpoint.
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPatchWebhookBadGatewayErrorResponseBody:
description: Bad Gateway
properties:
message:
description: Message of error
example: 'rpc error: code = Unknown desc = connection refused'
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksListWebhooksGatewayTimeoutErrorResponseBody:
description: Gateway timeout
properties:
message:
description: Message of error
example: context deadline exceeded
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksGetWebhookBadGatewayErrorResponseBody:
description: Bad Gateway
properties:
message:
description: Message of error
example: 'rpc error: code = Unknown desc = connection refused'
type: string
requestId:
description: The request ID; used when reaching out to support for issues with requests.
example: 8916e1c1
type: string
required:
- message
- requestId
type: object
WebhooksPostWebhooksInternalServerErrorResponseBody:
description: An internal server error occurred
properties:
message:
description: Message of error
example: Failed to execute GraphQL query.
type: string
r
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/samsara/refs/heads/main/openapi/samsara-webhooks-api-openapi.yml