Webhooks

🚧

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": {
      "InspectionHasStarted": {}
    },
    "details": {
      "inspection_id": "audit_047ef3d184014ce7a04bc65701b51234",
      "template_id": "template_5ac67d8738af471f9ad861232d8e1234",
      "org_id": "53465cd9-8933-4518-9b7e-c7a71b3b1234",
      "modify_time": {
        "seconds": 1689116664,
        "nanos": 272000000
      },
      "canonical_start_time": {
        "seconds": 1689116663,
        "nanos": 965000000
      },
      "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

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.

Actions

Incidents

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.

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"
  }
}