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 Tyler Freckmann 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": "Tyler Freckmann"
    },
    "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, you would perform the following GET request:

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

and you would receive the following payload back:

{
  "driverDocument": {
    "orgId": 53729,
    "driverId": 1654973,
    "id": "1654973_1587567275566",
    "driverCreatedAtMs": 1587567275566,
    "serverCreatedAtMs": 1587567281000,
    "serverUpdatedAtMs": 1587567281000,
    "dispatchJobId": 4335797294,
    "notes": "Some notes",
    "state": "Submitted",
    "documentType": "Stop Tasks",
    "vehicleId": 212014918732717,
    "fields": [
      {
        "value": "1234",
        "stringValue": "1234",
        "label": "Load #",
        "valueType": "ValueType_String"
      },
      {
        "value": [
          {
            "value": "Yes",
            "selected": true
          },
          {
            "value": "No",
            "selected": false
          }
        ],
        "multipleChoiceValue": [
          {
            "value": "Yes",
            "selected": true
          },
          {
            "value": "No",
            "selected": false
          }
        ],
        "label": "Did you drop the trailer?",
        "valueType": "ValueType_MultipleChoice"
      },
      {
        "value": 1,
        "numberValue": 1,
        "label": "# of pieces",
        "valueType": "ValueType_Number"
      },
      {
        "value": {
          "dateTimeMs": 1587567264724
        },
        "dateTimeValue": {
          "dateTimeMs": 1587567264724
        },
        "label": "Time unloaded",
        "valueType": "ValueType_DateTime"
      }
    ]
  }
}

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