Document Submission Webhook

Receive webhook notifications when drivers submit documents and retrieve the full document via the API.

Configure the Webhook

See the Webhooks guide for details on how to create a webhook. Specifically, you’ll want to configure a Document Submission alert to send to the webhook.

Once you’ve configured the webhook and the alert, you’ll receive a JSON payload like the following whenever a document is submitted:

{
  "eventId": "73746344-4b76-4e2a-ba19-3fa04b2f7038",
  "eventMs": 1587567280773,
  "eventType": "Alert",
  "event": {
    "alertEventUrl": "https://cloud.samsara.com/o/53729/alerts/incidents/v2/159570/5/1654973/1587567275566",
    "alertConditionDescription": "Document Submission",
    "alertConditionId": "DriverDocumentSubmitted",
    "details": "A Stop Tasks document was submitted by Driver Name at Wed, 22 Apr 2020 7:54am PDT. Document: https://cloud.samsara.com/o/53729/groups/54868/fleet/reports/documents/1654973/1587567275566 (ID: 1654973_1587567275566)",
    "driver": {
      "id": 1654973,
      "name": "Driver Name"
    },
    "orgId": 53729,
    "resolved": false,
    "startMs": 1587567275566,
    "summary": "Stop Tasks Submitted"
  }
}

In order to retrieve details about the document, you’ll need to extract the driver ID and document ID from the webhook payload.

The driver object in the webhook payload contains an id field.

The document ID is located in the details field of the webhook payload, and always has the following structure:

A {documentTemplateName} document was submitted by {driverName} at {submissionTime}. Document: {documentUrl} (ID: {documentId})

You can use regex or other string operations to extract the document ID from this field.

Retrieve the Document

The Fetches a document endpoint allows you to retrieve the document object using the driver ID and document ID collected from the webhook notification payload.

For example, using the driver ID and document ID extracted from the webhook payload above:

curl --request GET 'https://api.samsara.com/v1/fleet/drivers/1654973/documents/1654973_1587567275566' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

The response includes a driverDocument object with orgId, driverId, id, driverCreatedAtMs, serverCreatedAtMs, serverUpdatedAtMs, dispatchJobId, notes, state, documentType, vehicleId, and a fields array containing each field’s label, valueType, and value.

See the Document Object overview for details on the document object.