Webhooks allow you to receive notifications when specific events occur in your organization, such as an inspection being completed or a new action being assigned. These notifications are sent as HTTP POST requests to a URL you specify.

Webhooks are set up at the organization level. Any event that occurs in the top-level organization that registered the webhook can trigger it. Events are not scoped per user.

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

To keep payloads lightweight, webhook data includes only a subset of the information related to the event. For example, the following payload is 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": {}
    }
  }
}

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

Webhook delivery and retries

Webhook delivery operates on a best-effort basis. There is no guarantee that a given webhook will be delivered within a certain time frame or delivered at all.

If the receiving service responds with an error (e.g., a 4xx or 5xx HTTP response), the webhook is retried up to 4 times, with a 100-second delay between each attempt.

Webhook events are also not guaranteed to arrive in order, and duplicate deliveries may occur. Your system should handle retries and de-duplicate events where necessary using the webhook ID or event timestamp.

To ensure completeness, use the Search modified inspections endpoint to identify inspections that changed within a given date range and compare them with received webhook events.

Requirements

To receive webhook notifications, the authentication method used to register the webhook must have the correct permissions. Permissions differ depending on whether it is for a user or a service user.

Users must have the “Administrator” permission. This permission set gives a user full control of their organization, including management of users, groups, sites, and permissions.
Service users must have the “Override permissions: Manage all data” permission. This permission allows service users to edit, archive, and delete all templates, inspections, issues, and actions. It also overrides any existing access rules. It is required for service users to receive webhook payloads.

Supported webhook trigger events

We currently support the following webhook categories:

Inspections webhooks
Actions webhooks
Incidents webhooks
Media webhooks
Training webhooks

Inspections

Receive notifications when inspection-related events occur.

🚧
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.

📘
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.

Trigger event	Description
`TRIGGER_EVENT_INSPECTION`	All inspection events.

Trigger event	Description
`TRIGGER_EVENT_INSPECTION_METADATA`	When any of the metadata events in this inspections table is triggered.
`TRIGGER_EVENT_INSPECTION_HAS_STARTED`	When an inspection is started.
`TRIGGER_EVENT_INSPECTION_CLONED`	When an inspection is duplicated.
`TRIGGER_EVENT_INSPECTION_COMPLETED_STATUS`	When an inspection is marked as complete or incomplete.
`TRIGGER_EVENT_INSPECTION_LOCATION`	When an inspection's start or completion location is captured. This only applies to inspections started or completed on the mobile app.
`TRIGGER_EVENT_INSPECTION_DURATION`	When an inspection's duration is updated.
`TRIGGER_EVENT_INSPECTION_ARCHIVED_STATUS`	When an inspection is archived or restored from the archive.
`TRIGGER_EVENT_INSPECTION_DELETED_STATUS`	When an inspection is deleted.
`TRIGGER_EVENT_INSPECTION_OWNER`	When an inspection's owner is set.
`TRIGGER_EVENT_INSPECTION_ACCESS`	When an inspection's access rules are updated.
`TRIGGER_EVENT_INSPECTION_ORGANISATION`	When an inspection's associated organization is updated. This shouldn't be triggered in most cases.

Trigger event	Description
`TRIGGER_EVENT_INSPECTION_ITEM_UPDATED`	When any of the events in this inspection items table is triggered.
`TRIGGER_EVENT_INSPECTION_ITEM_SITE`	When the response to a site question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_TEXT`	When the response to a text answer question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_TEMPERATURE`	When the response to a number answer (temperature format) question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_ADDRESS`	When the response to a location question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_ASSET`	When the response to an asset question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_DATETIME`	When the response to a date & time question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_CHECKBOX`	When the response to a checkbox question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_LIST`	When 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_QUESTION`	When the response to a multiple-choice question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_MEDIA`	When the response to a media question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_DRAWING`	When the response to an annotation question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_SIGNATURE`	When the response to a signature question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_SLIDER`	When the response to a slider question is updated.
`TRIGGER_EVENT_INSPECTION_ITEM_NOTE`	When 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 event	Description
`TRIGGER_EVENT_INSPECTION_STARTED`	Inspection started. (Deprecated. Please use `TRIGGER_EVENT_INSPECTION_HAS_STARTED`)
`TRIGGER_EVENT_INSPECTION_UPDATED`	Inspection updated. (Deprecated. Please use `TRIGGER_EVENT_INSPECTION`)
`TRIGGER_EVENT_INSPECTION_COMPLETED`	Inspection completed. (Deprecated. Please use `TRIGGER_EVENT_INSPECTION_COMPLETED_STATUS`)
`TRIGGER_EVENT_INSPECTION_ARCHIVED`	Inspection archived. (Deprecated. Please use `TRIGGER_EVENT_INSPECTION_ARCHIVED_STATUS`)
`TRIGGER_EVENT_INSPECTION_UNARCHIVED`	Inspection unarchived. (Deprecated. Please use `TRIGGER_EVENT_INSPECTION_ARCHIVED_STATUS`)

Actions

Receive notifications when actions are created or updated.

Trigger event	Description
`TRIGGER_EVENT_ACTION_UPDATED`	Action updated.
`TRIGGER_EVENT_ACTION_CREATED`	Action created.
`TRIGGER_EVENT_ACTION_TITLE_UPDATED`	Action title updated.
`TRIGGER_EVENT_ACTION_DESCRIPTION_UPDATED`	Action description updated.
`TRIGGER_EVENT_ACTION_DATE_DUE_UPDATED`	Action date due updated.
`TRIGGER_EVENT_ACTION_STATUS_UPDATED`	Action status updated.
`TRIGGER_EVENT_ACTION_PRIORITY_UPDATED`	Action priority updated.
`TRIGGER_EVENT_ACTION_COLLABORATORS_UPDATED`	Action collaborators updated.
`TRIGGER_EVENT_ACTION_SITE_UPDATED`	Action site updated.
`TRIGGER_EVENT_ACTION_DELETED`	Action deleted.
`TRIGGER_EVENT_ACTION_ASSET_UPDATED`	Action asset updated.
`TRIGGER_EVENT_ACTION_LABELS_UPDATED`	Action labels updated.

Incidents

Receive notifications for issue-related events.

Trigger event	Description
`TRIGGER_EVENT_INCIDENT_UPDATED`	Issue updated.
`TRIGGER_EVENT_INCIDENT_CREATED`	Issue created.
`TRIGGER_EVENT_INCIDENT_TITLE_UPDATED`	Issue title updated.
`TRIGGER_EVENT_INCIDENT_DESCRIPTION_UPDATED`	Issue description updated.
`TRIGGER_EVENT_INCIDENT_DATE_DUE_UPDATED`	Issue date due updated.
`TRIGGER_EVENT_INCIDENT_STATUS_UPDATED`	Issue status updated.
`TRIGGER_EVENT_INCIDENT_PRIORITY_UPDATED`	Issue priority updated.
`TRIGGER_EVENT_INCIDENT_COLLABORATORS_UPDATED`	Issue assignee updated.
`TRIGGER_EVENT_INCIDENT_CATEGORY_UPDATED`	Issue category updated.
`TRIGGER_EVENT_INCIDENT_SITE_UPDATED`	Issue site updated.
`TRIGGER_EVENT_INCIDENT_DELETED`	Issue 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 event	Description
`TRIGGER_EVENT_MEDIA_UPLOADED`	Media 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"
  }
}

Training

Receive notifications for training related events. For retrieving training information refer to Training.