Update inspection responses based on selected responses

This guide explains how to automatically update inspection responses based on specific responses selected during the inspection. For example, you would like to update the Site name and Site manager fields based on the user's answer in the site response type. This approach is helpful for auto-filling data from external systems like location or client details to reduce manual entry and create custom calculations based on inspection data.

🚧
Changes made via the API will not be visible in an open inspection until the user exits and reopens it.

You can update inspection responses automatically in three steps:

Register a webhook and receive inspection events.
Fetch the information to update in the inspection
Update the inspection responses.

Register a webhook and receive inspection events

SafetyCulture offers various webhooks to notify you of platform events. For this scenario, use the TRIGGER_EVENT_INSPECTION_ITEM_UPDATED event, which tracks when an inspection item is updated. Once it is updated, your server receives a POST request with the relevant event data.

curl --request POST \
     --url https://api.safetyculture.io/webhooks/v1/webhooks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {api_token}' \
     --header 'content-type: application/json' \
     --data '
{
  "trigger_events": [
    "TRIGGER_EVENT_INSPECTION_ITEM_UPDATED"
  ],
  "url": "https://example.com"
}
'

Upon any inspection completion, your server will receive an HTTP POST request with a payload similar to the following:

{
  "webhook_id": "d1ddb5d8-8ee0-41c7-bda5-cfab6740d465",
  "version": "3.0.0",
  "event": {
    "date_triggered": "2024-05-22T04:11:15Z",
    "event_types": [
      "TRIGGER_EVENT_INSPECTION",
      "TRIGGER_EVENT_INSPECTION_ITEM_UPDATED",
      "TRIGGER_EVENT_INSPECTION_ITEM_SITE"
    ],
    "triggered_by": {
      "user": "user_f2dad30f787b4b5da890655ab8ac8ddf",
      "organization": "1deba7cb-6354-4377-9c35-7ccb56180d4e"
    }
  },
  "resource": {
    "id": "audit_b432cc30787c4606a08645552a24193a",
    "type": "INSPECTION"
  },
  "data": {
    "inspection_site_set": {
      "site": {
        "folder_id": "c1293ede-04ca-4be5-bd90-bc6ea01360b6"
      }
    },
    "details": {
      "inspection_id": "audit_b432cc30787c4606a08645552a24193a",
      "template_id": "template_eebb5009bdd247f783c9db74ce578a92",
      "org_id": "1deba7cb-6354-4377-9c35-7ccb56180d4e",
      "modify_time": "2024-05-22T04:11:15.618Z",
      "canonical_start_time": "2024-05-22T04:11:08.838Z",
      "score": {}
    }
  }
}

📘
The payload will vary depending on the type of question answered. In this example, the payload is associated with setting a site question.

Fetch the information to update in the inspection

Use the selected site ID from the event payload to retrieve the information you want to update in the inspection. This step varies based on your data source.

Update the inspection responses

To identify the item_id to update, you can use the Get an inspection API with an example inspection ID. This will return the item_id and label in a given inspection.

curl --request PUT \
     --url https://api.safetyculture.io/audits/{inspection_id} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {api_token}' \
          --data '
{
  "items": [
    {
      "type": "text",
      "responses": {
        "text": "Sydney - Site XYZ"
      },
      "item_id": "d0e3e7aa-03ed-43ea-867e-b61ece76f099"
    },
    {
      "type": "text",
      "responses": {
        "text": "Joe Bloggs"
      },
      "item_id": "d5cc82a1-c1cb-4543-9bab-4422f53f88ee"
    }
  ]
}
'

See Update an inspection for more details on updating an inspection.

A complete example of this might look like this:

// https://developer.safetyculture.com/reference/authentication
const ACCESS_TOKEN = 'my-access-token';

// Templates we want to run this integration against
const TEMPLATE_IDS = [
  'template_eebb5009bdd247f783c9db74ce578a92',
  'template_xyx123'
]

// The item ID for "Site Name"
const ITEM_ID_SITE_NAME = 'd0e3e7aa-03ed-43ea-867e-b61ece76f099';
// The item ID for "Site Manager"
const ITEM_ID_SITE_MANAGER = 'd5cc82a1-c1cb-4543-9bab-4422f53f88ee';

// The payload received from https://developer.safetyculture.com/reference/webhooks
async function receiveSafetyCultureWebhook(payload) {
  // Only listen to events where a site has been updated.
  if (!payload.data.inspection_site_set) {
    return;
  }

  // Only listen to events for a specific templates in SafetyCulture.
  if (TEMPLATE_IDS.includes(payload.details.template_id)) {
    return;
  }
  
  const inspection_id = payload.details.inspection_id;
  const site_id = payload.data.inspection_site_set.site.folder_id;

  // retrieve the site details from our internal system.
  // This should be replaced with the system containing that information.
  const siteDetails = await myApi.getSiteDetails(site_id);
  
  // Retrieve the current owner of the inspection.
  const response = await fetch(`https://api.safetyculture.io/audits/${inspection_id}`, {
    method: 'GET',
    headers: {
      accept: 'application/json',
      authorization: `Bearer ${ACCESS_TOKEN}`
    }
  });
  const inspection = await response.json();
  const owner_id = inspection.audit_details.authorship.owner_id;

  // Reassign the ownership.
  await fetch(`https://api.safetyculture.io/audits/${inspection_id}`,  {
    method: 'PUT',
    headers: {
      accept: 'application/json',
      'content-type': 'application/json',
      authorization: `Bearer ${ACCESS_TOKEN}`
    },
    body: JSON.stringify({
      items: [
        {
          type: 'text',
          responses: {text: siteDetails.name},
          item_id: ITEM_ID_SITE_NAME
        },
        {
          type: 'text',
          responses: {text: siteDetails.manager},
          item_id: ITEM_ID_SITE_MANAGER
        }
      ]
    })
  });
}