Webhooks

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

🚧

You must have the "Admin" permission 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. The format of a webhook payload (here for the TRIGGER_EVENT_INSPECTION_STARTED event) is included as example code.

{
  "version": "1.0.0",
  "workflow_id": "workflow_8abb7bff902a43a5b3bd498f4bebb42j",
  "event": {
    "date_triggered": "2017-06-29T05:15:19.136Z",
    "event_types": [
      "audit_started"
    ],
    "triggered_by": {
      "type": "user",
      "user": "user_bb5b6ba050bf43c1b447b6f299de4b67",
      "name": "John Smith"
    }
  },
  "data": {
    "audit": {
      "template_id": "template_ca59d625954f4d51baf394400d6e3z87",
      "audit_id": "audit_7e9ee886325a4fb096989c3e2896e876",
      "archived": false,
      "created_at": "2017-06-29T05:15:18.511Z",
      "modified_at": "2017-06-29T05:15:18.511Z",
      "audit_data": {
        "score": 0,
        "total_score": 0,
        "name": "",
        "duration": 0,
        "authorship": {
          "device_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "owner": "John Smith",
          "owner_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "author": "John Smith",
          "author_id": "user_bb5b6ba050bf43c1b447b6f299de4b67"
        },
        "date_completed": null,
        "date_modified": "2017-06-29T05:15:18.509Z",
        "date_started": "2017-06-29T05:15:18.509Z"
      },
      "template_data": {
        "authorship": {
          "device_id": "8a582619-95e9-43e8-b671-6h765745b200",
          "owner": "John Smith",
          "owner_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "author": "John Smith",
          "author_id": "user_bb5b6ba050bf43c1b447b6f299de4b67"
        },
        "metadata": {
          "description": "",
          "name": "test"
        }
      },
      "header_items": [
        {
          "item_id": "f3245d39-ea77-11e1-aff1-0800200c9a78",
          "label": "Title Page",
          "type": "section",
          "children": [
            "f3245d46-ea77-11e1-aff1-0800200c9a66",
            "f3245d40-ea77-11e1-aff1-0800200c9a66",
            "f3245d41-ea77-11e1-aff1-0800200c9a66",
            "f3245d42-ea77-11e1-aff1-0800200c9a66",
            "f3245d43-ea77-11e1-aff1-0800200c9a66",
            "f3245d44-ea77-11e1-aff1-0800200c9a66",
            "f3245d45-ea77-11e1-aff1-0800200c9a66"
          ]
        },
        {
          "parent_id": "f3245d39-ea77-11e1-aff1-0800200c9a66",
          "item_id": "f3245d46-ea77-11e1-aff1-0800200c9a66",
          "label": "Document No.",
          "type": "textsingle",
          "responses": {
            "text": "000027"
          }
        },
        {
          "parent_id": "f3245d39-ea77-11e1-aff1-0800200c9a66",
          "item_id": "f3245d45-ea77-11e1-aff1-0800200c9a66",
          "label": "Personnel",
          "type": "text"
        }
      ]
    },
    "template": {
      "template_id": "template_ca59d625954f4d51baf394400d6e3z87",
      "name": "test"
    }
  }
}

If the service receiving the webhook replies with an error, the webhook will be retried with an exponentially increasing delay. A total of 4 attempts are made, each with a delay of 100 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 iAuditor web application or using the API directly), webhooks will only be triggered when these inspections are synced to the iAuditor backend.

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_INSPECTION_STARTEDInspection started.
TRIGGER_EVENT_INSPECTION_UPDATEDInspection updated.
TRIGGER_EVENT_INSPECTION_COMPLETEDInspection completed.
TRIGGER_EVENT_INSPECTION_ARCHIVEDInspection archived.
TRIGGER_EVENT_INSPECTION_UNARCHIVEDInspection unarchived.

Actions

Trigger eventDescription
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.

Incidents

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