Swipeguide: Webhooks for Checklist Alerts

General​

Checklist Alerts are used for reporting problems in real time. They are only visible when Checklists are enabled on the platform. An operator can report a problem and send the current state of the check, including the feedback and any media attached, by pressing the "Report issue" button.

Pre-requisites​

Checklist Alerts requires your IT support to provide one or more webhooks which can subscribe to SwipeGuide and receive the payload from the SwipeGuide platform when the "Report Issue" is triggered. It may require your team to further integrate the payload data into your internal or external systems.

Getting Started​

To start using Checklist Alerts, ask your Customer Success Manager to enable Checklist Alerts on your platform.

This will enable a section underneath Platform Settings where a webhook can be configured for the entire Platform, or for more flexibility, several recipients can be defined and specified later on the Checklist level on Guide Creation and Editing.

Platform Level Alerts​

Platform level webhooks allow setting a single webhook URL that will be called on every Checklist Alert that is triggered in the platform. This is useful for platforms that want to have a single endpoint for all escalations.

When a checklist check is escalated, an HTTP POST request will be sent to the provided webhook URL with a different payload format depending on the URL:

Payload Formats​

• Microsoft Teams: If the webhook URL contains "webhook.office.com" or is a Microsoft Teams Workflow URL, the payload will be formatted according to Microsoft Teams' specifications. (As can be seen in the Microsoft Teams documentation).

• Swipeguide Webhook format: All other URLs will receive the payload it the SwipeGuide Webhook format.

The payload sent to the webhook URL will be a JSON object with the following properties:

• checklistAnswerItem: The object that contains the information about the check that was escalated. It contains the following fields:
  • value: The value of the check at the time the issue was reported. It may be true, false or null
  • feedback: The written text provided by the users in the "Add Details" dialog when the issue was reported. This field may be null.
  • mediaUrl: The image URL uploaded by user in the "Add Details" dialog when the issue was reported. This field may be null.
  • guideVersionId: The published version of the guide when the issue was reported.
  • stepId The identifier of the check where the escalation was triggered.
• user: The id, fullName, and email address of the user if they are logged in with email address or SSO when they report the issue. If the platform is not protected or if the workspace is only password protected, the user will be null.
• domain: The name of the workspace where the Checklist was published when the issue was reported
• slug: The unique identifier of the url of the workspace. (For example: https://myworkspace-swipeguide.swipeguide.com the slug is "myworkspace".)
• context: Details about the context where the escalation happened with id and text label for the check, checklist, topic, guide, and id and name of the owning team of the guide.

{
  "checklistAnswerItem": {
    "stepId": "3ca87a36-cff8-49f3-8c0e-32cdde20154a",
    "value": false,
    "feedback": "This is really urgent",
    "mediaUrl": "https://res.cloudinary.com/swipe-staging/image/upload/v1673613331/app/h2ujdmzjqgoruaicpysn.png",
    "guideVersionId": "6304bf4ee23927038781f931"
  },
  "user": {
    "id": "dbc5c0de-6c6f-4bc3-a064-f9e97dc1c4d3",
    "email": "user@gmail.com",
    "fullName": "Full Name"
  },
  "domain": {
    "id": "f57c624c-682d-4bbc-a566-4e90d0b28f78",
    "name": "SwipeGuide support",
    "slug": "support"
  },
  "context": {
    "check": {
      "id": "3ca87a36-cff8-49f3-8c0e-32cdde20154a",
      "instruction": "Check content"
    },
    "checklist": {
      "id": "f20ba269-7a72-4070-b445-ef19e4baf03f",
      "title": "Checklist title"
    },
    "guide": {
      "id": "fc9595ec-cf4e-4e9f-908e-321cf2023a79",
      "title": "Guide title"
    },
    "team": {
      "id": "3b995b0f-ae63-43e9-a0d1-9f53f6609fe7",
      "name": "Team Name"
    },
    "topic": {
      "id": "2ae2d09d-ec4d-42ee-942b-2c15550d568a",
      "title": "Topic title"
    }
  }
}

Configurable Checklist Alerts​

1. From Checklist Alerts menu item in Platform Settings, click on the "Recipients" tab.
2. Press the green "+" button action button to create a new Alert Recipient. You may specify that the payload will be sent to Microsoft Teams, or a Custom Webhook of your choice that will receive the payload sent from SwipeGuide in the format above.
3. As an Editor or an Admin, when editing the Guide, click on the menu item on the Checklist "Set Alert Recipients". Here you may specify up to 4 recipients to send the payload of the Checklist to whenever "Report Issue" is pressed on the Check item.

Data & Analytics​

Currently, SwipeGuide does not store the payload of the Checklist Alert that is sent to your Webhook, so if the data is required to be stored for historical purposes, we recommend that that you store this data in your external systems.

Troubleshooting & Errors​

If you experience errors while using Checklist Alerts, please check the validity of the webhook URL you have provided and if the endpoint is reachable. Otherwise please check that you have a valid authentication token to send the request.

For further assistance, please contact Customer Support with the Steps to Reproduce for any issue you are experiencing.