Webhooks

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

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.

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

Receive notifications when actions are created or updated.

Incidents

Receive notifications for issue-related events.

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