API

Webhooks

Webhooks allow third-party services to receive near real-time inspection event notifications from SafetyCulture.

🚧

You must have the "Administrator" permission set to use webhook endpoints.

Webhooks will be sent in the form of a POST HTTP request to the specified URL when an event like inspection starting, updating, completing, archiving, unarchiving takes place.

Any inspection event in the top-level organization of the user that registered the webhook will trigger the webhook. In other words, webhooks are set up per organization, not per user account.

To create a webhook, register the URL within your application that will receive the webhook payload sent when the event is triggered.

To keep the payload size manageable, the webhook payload only contains a subset of the inspection and template information. For example, the following is a payload from the TRIGGER_EVENT_INSPECTION_HAS_STARTED event.

{
  "webhook_id": "5378baaa-a470-48cc-8f11-ae2893551234",
  "version": "3.0.0",
  "event": {
    "date_triggered": "2023-07-11T23:04:24Z",
    "event_types": [
      "TRIGGER_EVENT_INSPECTION",
      "TRIGGER_EVENT_INSPECTION_METADATA",
      "TRIGGER_EVENT_INSPECTION_HAS_STARTED"
    ],
    "triggered_by": {
      "user": "user_b0bc1fcbef1a4ecf9f9b3d2dbddb1234",
      "organization": "53465cd9-8933-4518-9b7e-c7a71b3b1234"
    }
  },
  "resource": {
    "id": "audit_047ef3d184014ce7a04bc65701b51234",
    "type": "INSPECTION"
  },
  "data": {
    "event": {
      "inspection_has_started": {}
    },
    "details": {
      "inspection_id": "audit_047ef3d184014ce7a04bc65701b51234",
      "template_id": "template_5ac67d8738af471f9ad861232d8e1234",
      "org_id": "53465cd9-8933-4518-9b7e-c7a71b3b1234",
      "modify_time": "2022-05-10T05:24:56Z",
      "canonical_start_time": "2022-05-10T05:24:56Z",
      "score": {}
    }
  }
}

If the service receiving the webhook replies with an error, the webhook will be retried with a delay. A total of 4 attempts are made, each with a delay of 100 seconds in between:

Webhook delivery is on a best effort basis, no guarantee is provided that a particular webhook will be delivered within a time frame or at all. The Search modified inspections functionality can help client code verify which inspections changed in a given date range and to compare with received webhooks to ensure completeness.

When inspections are processed on a mobile device (as opposed to the SafetyCulture web app or using the API directly), webhooks will only be triggered when these inspections are synced to the SafetyCulture server.

In the following sections we describe how to perform CRUD operations on webhooks.

🚧

Ensure that inspections containing media are fully synced before exporting a PDF or Word report export as a result of receiving a webhook notification to avoid exported reports being corrupt files. To check if media is uploaded use the media download endpoints or wait for a reasonable amount of time before initiating a report export.

Supported Trigger Events

These are the supported trigger events for webhooks.

Inspections

Trigger eventDescription
TRIGGER_EVENT_INSPECTIONAll inspection events.
Trigger eventDescription
TRIGGER_EVENT_INSPECTION_METADATAWhen any of the metadata events in this inspections table is triggered.
TRIGGER_EVENT_INSPECTION_HAS_STARTEDWhen an inspection is started.
TRIGGER_EVENT_INSPECTION_CLONEDWhen an inspection is duplicated.
TRIGGER_EVENT_INSPECTION_COMPLETED_STATUSWhen an inspection is marked as complete or incomplete.
TRIGGER_EVENT_INSPECTION_LOCATIONWhen an inspection's start or completion location is captured. This only applies to inspections started or completed on the mobile app.
TRIGGER_EVENT_INSPECTION_DURATIONWhen an inspection's duration is updated.
TRIGGER_EVENT_INSPECTION_ARCHIVED_STATUSWhen an inspection is archived or restored from the archive.
TRIGGER_EVENT_INSPECTION_DELETED_STATUSWhen an inspection is deleted.
TRIGGER_EVENT_INSPECTION_OWNERWhen an inspection's owner is set.
TRIGGER_EVENT_INSPECTION_ACCESSWhen an inspection's access rules are updated.
TRIGGER_EVENT_INSPECTION_ORGANISATIONWhen an inspection's associated organization is updated. This shouldn't be triggered in most cases.
Trigger eventDescription
TRIGGER_EVENT_INSPECTION_ITEM_UPDATEDWhen any of the events in this inspection items table is triggered.
TRIGGER_EVENT_INSPECTION_ITEM_SITEWhen the response to a site question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_TEXTWhen the response to a text answer question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_TEMPERATUREWhen the response to a number answer (temperature format) question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_ADDRESSWhen the response to a location question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_ASSETWhen the response to an asset question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_DATETIMEWhen the response to a date & time question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_CHECKBOXWhen the response to a checkbox question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_LISTWhen the response to a multiple-choice question is updated. A list item is a multiple-choice question that either has more than 5 responses, multiple selection enabled, a response that contains more than 30 characters, or a Global Response Set.
TRIGGER_EVENT_INSPECTION_ITEM_QUESTIONWhen the response to a multiple-choice question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_MEDIAWhen the response to a media question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_DRAWINGWhen the response to an annotation question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_SIGNATUREWhen the response to a signature question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_SLIDERWhen the response to a slider question is updated.
TRIGGER_EVENT_INSPECTION_ITEM_NOTEWhen the note for a question is updated.

The following table contains deprecated inspection trigger events. Registration of these events will be discontinued in the near future. Alternatives have been suggested in the description.
Note: Deprecated trigger events cannot be registered together with non-deprecated trigger events.

Trigger eventDescription
TRIGGER_EVENT_INSPECTION_STARTEDInspection started. (Deprecated. Please use TRIGGER_EVENT_INSPECTION_HAS_STARTED)
TRIGGER_EVENT_INSPECTION_UPDATEDInspection updated. (Deprecated. Please use TRIGGER_EVENT_INSPECTION)
TRIGGER_EVENT_INSPECTION_COMPLETEDInspection completed. (Deprecated. Please use TRIGGER_EVENT_INSPECTION_COMPLETED_STATUS)
TRIGGER_EVENT_INSPECTION_ARCHIVEDInspection archived. (Deprecated. Please use TRIGGER_EVENT_INSPECTION_ARCHIVED_STATUS)
TRIGGER_EVENT_INSPECTION_UNARCHIVEDInspection unarchived. (Deprecated. Please use TRIGGER_EVENT_INSPECTION_ARCHIVED_STATUS)

Actions

Trigger eventDescription
TRIGGER_EVENT_ACTION_UPDATEDAction updated.
TRIGGER_EVENT_ACTION_CREATEDAction created.
TRIGGER_EVENT_ACTION_TITLE_UPDATEDAction title updated.
TRIGGER_EVENT_ACTION_DESCRIPTION_UPDATEDAction description updated.
TRIGGER_EVENT_ACTION_DATE_DUE_UPDATEDAction date due updated.
TRIGGER_EVENT_ACTION_STATUS_UPDATEDAction status updated.
TRIGGER_EVENT_ACTION_PRIORITY_UPDATEDAction priority updated.
TRIGGER_EVENT_ACTION_COLLABORATORS_UPDATEDAction collaborators updated.
TRIGGER_EVENT_ACTION_SITE_UPDATEDAction site updated.
TRIGGER_EVENT_ACTION_DELETEDAction deleted.
TRIGGER_EVENT_ACTION_ASSET_UPDATEDAction asset updated.
TRIGGER_EVENT_ACTION_LABELS_UPDATEDAction labels updated.

Incidents

Trigger eventDescription
TRIGGER_EVENT_INCIDENT_UPDATEDIssue updated.
TRIGGER_EVENT_INCIDENT_CREATEDIssue created.
TRIGGER_EVENT_INCIDENT_TITLE_UPDATEDIssue title updated.
TRIGGER_EVENT_INCIDENT_DESCRIPTION_UPDATEDIssue description updated.
TRIGGER_EVENT_INCIDENT_DATE_DUE_UPDATEDIssue date due updated.
TRIGGER_EVENT_INCIDENT_STATUS_UPDATEDIssue status updated.
TRIGGER_EVENT_INCIDENT_PRIORITY_UPDATEDIssue priority updated.
TRIGGER_EVENT_INCIDENT_COLLABORATORS_UPDATEDIssue assignee updated.
TRIGGER_EVENT_INCIDENT_CATEGORY_UPDATEDIssue category updated.
TRIGGER_EVENT_INCIDENT_SITE_UPDATEDIssue site updated.
TRIGGER_EVENT_INCIDENT_DELETEDIssue deleted.

Media

The media uploaded event triggers once a full media file has been uploaded to SafetyCulture.
This event only gets triggered by uploaded image media files. Videos and PDF files are not supported.

Trigger eventDescription
TRIGGER_EVENT_MEDIA_UPLOADEDMedia uploaded.

These events will return a JSON structure similar to.

{
  "webhook_id": "8475debb-a531-4fc6-b25f-eaeee6e75b82",
  "event": {
    "date_triggered": "2022-05-10T05:24:56Z",
    "event_types": ["TRIGGER_EVENT_MEDIA_UPLOADED"],
    "triggered_by": {
      "user_type": "user",
      "user": "fd2a2355-da0f-499e-b7a6-4df5c4c89722",
      "organization": "fac4e871-cc83-403e-b1d7-007b5809f8e7"
    }
  },
  "resource": {
    "id": "94924cfa-23c4-4211-917f-e00b822ee1b2",
    "type": "TASK"
  },
  "data": {
    "media_id": "37ceed41-9371-4851-995b-6869984a3e65",
    "media_type": "IMAGE",
    "media_url": "https://api-media-download.safetyculture.com/originals/3/7/c/e/37ceed41-9371-4851-995b-6869984a3e65?<signature>",
    "content_length": 2515,
    "file_extension": ".png"
  }
}