Webhooks allow third-party services to receive near real-time inspection event notifications from SafetyCulture.
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 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 event | Description |
|---|---|
TRIGGER_EVENT_INSPECTION_STARTED | Inspection started. |
TRIGGER_EVENT_INSPECTION_UPDATED | Inspection updated. |
TRIGGER_EVENT_INSPECTION_COMPLETED | Inspection completed. |
TRIGGER_EVENT_INSPECTION_ARCHIVED | Inspection archived. |
TRIGGER_EVENT_INSPECTION_UNARCHIVED | Inspection unarchived. |
Actions
| Trigger event | Description |
|---|---|
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. |
Incidents
| Trigger event | Description |
|---|---|
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>"
}
}