Webhooks

Webhooks Overview

Webhooks are a powerful tool that helps to extend your tie into events in your DeskDirector instance and are best used in automations. You can subscribe to webhooks programmatically or can use them with low/no-code platforms like Zapier or Microsoft Power Automate. You can also use services like PostBin to test a webhook's payload.

Here are some of the common scenarios where you may want to use webhooks:

• Notify technicians in Microsoft Teams or Slack once a ticket is updated
• Notify technicians in Microsoft Teams or Slack when a user has requested chat
• Achieve multi-tier approval when tickets get marked with Approval Required
• Send emails to users with form entries included in the email, formatted with detailed information from the ticket/chat request

How to Use Webhooks

You can manage your webhooks via the Admin portal under Advanced > Webhook. There will be a slider just beside the "Webhook" header to enable or disable webhooks that you've set up.

Once on the Webhook page, you will see 4 tabs.

Registered Webhooks

This tab shows the current active webhooks for your site and allows you to create new webhooks. It lists the webhook description alongside the webhook receiver URL and the ticket/chat event it is assigned to. You can display the full webhook receiver URL and secret by clicking the "Display detail" button.

If needed, you can delete a webhook or regenerate a secret for it as well.

Deleted Webhooks

This tab lists recent webhooks that have been removed from your instance. Webhooks can be deleted manually from the "Registered Webhooks" tab or by script. 

Webhook Security

This tab explains how security is done and handled for webhooks to make sure your webhook request authenticates with DeskDirector.

Payload Sample

This tab will show a sample schema payload when handling webhooks for events. This comes in handy when trying to integrate with other platforms like Zapier or Microsoft Power Automate, as they will require/expect a JSON schema.

Subscribing to a Webhook

DeskDirector can call webhooks whenever a ticket is updated, a chat session is created or updated, and more. This is a really powerful way to customise your chat workflow.

1. Open the Admin Portal and head to Advanced > Webhook

   

2. Select Create Webhook > Add ticket/chat/custom webhook

   

3. Enter in a Description and Receiver URL that will receive payloads when the webhook is called
4. Select which events you would like to listen for

   

5. Test your webhook by performing an action that would trigger the desired event.

Webhook Ideas

• Send an email to a manager whenever a chat session is abandoned by a user.
• Create a ticket to follow up on abandoned chat requests.
• Send an email to your technicians if a chat session remains in the 'handled' status for more than 1 hour. It's unlikely that a chat session is ongoing for more than an hour, so this is a good reminder for your technicians to close their chat sessions and create tickets.

Payloads

Chat Webhook Payload

The payload will contain a list of events. Each event represents one of the chat sessions change. Below is an explanation for some of the properties in the JSON object that gets delivered.

• status.created: a session has been created
• status.handled: a session has been handled by a technician
• status.missed: a user has left a session without being answered/acknowledged
• status.callback: a user has left a callback request
• status.completed: a session has been closed as completed
• pastStatus: a list of past status.
• type.request: chat request from end user. (portal)
• type.push: push chat, which is initialised by an agent from the TECH Portal
• reference: If the chat is regarding a ticket, type will be ticket and id will be ticket ID.
• creator: User who created this chat session. It can reference a member or contact.
• targetUsers: Chat invitation list. When you invite other users, they will be inside the target users list first; if they accept, it will move to the users list.
• users: Whoever is currently in the chat session.
• partitions: All the users who have ever entered this chat session.

Example Payload

[
	{
		"msp": "dd",
		"id": "1586985009-627B",
		"name": "Test",
		"type": "request",
		"status": "handled",
		"pastStatus": ["created", "handled"],
		"report": {
			"creatorWaited": null,
			"handledDateTime": null,
			"chatDuration": null
		},
		"reference": {
			"type": "ticket",
			"id": "22282"
		},
		"creator": {
			"entityId": 106,
			"name": "Jason He",
			"userId": "dd~c~106",
			"company": {
				"entityId": 19348,
				"name": "DeskDirector",
				"identifier": "DeskDirectorLtd"
			}
		},
		"callback": null,
		"targetUsers": [],
		"closeRecord": null,
		"users": [
			{
				"entityId": 106,
				"name": "Jason He",
				"userId": "dd~c~106",
				"company": {
					"entityId": 19348,
					"name": "DeskDirector",
					"identifier": "DeskDirectorLtd"
				}
			}
		],
		"participants": [
			{
				"entityId": 106,
				"name": "Jason He",
				"userId": "dd~c~106",
				"company": {
					"entityId": 19348,
					"name": "DeskDirector",
					"identifier": "DeskDirectorLtd"
				}
			}
		],
		"lastMessageId": null,
		"createdDateTime": "2020-04-15T21:10:09.5895683Z",
		"lastModifiedDateTime": "2020-04-15T21:12:00.9897216Z",
		"meta": {
			"canAccess": true
		}
	}
]

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "name", "type", "status", "pastStatus", "report", "creator", "closedDateTime", "users", "participants", "lastModifiedDateTime"],
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "type": { "enum": ["request", "push"] },
    "status": { "$ref": "#/definitions/ChatSessionStatus" },
    "pastStatus": {
      "type": "array",
      "items": { "$ref": "#/definitions/ChatSessionStatus" }
    },
    "report": {
      "type": "object",
      "required": ["creatorWaited", "handledDateTime", "chatDuration"],
      "properties": {
        "creatorWaited": { "type": "number" },
        "handledDateTime": { "type": "string" },
        "chatDuration": { "type": "number" }
      }
    },
    "reference": {
      "type": "object",
      "required": ["type", "id"],
      "properties": {
        "type": { "const": "ticket" },
        "id": { "type": "string" }
      }
    },
    "creator": { "$ref": "#/definitions/User" },
    "callback": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": { "enum": ["phone", "chat"] },
        "phone": { "type": "string" },
        "note": { "type": "string" },
        "preferredTime": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["start", "end"],
            "properties": {
              "start": { "type": "string" },
              "end": { "type": "string" }
            }
          }
        }
      }
    },
    "targetUsers": {
      "type": "array",
      "items": { "$ref": "#/definitions/User" }
    },
    "closeRecord": {
      "type": "object",
      "required": ["user", "lastModifiedDateTime"],
      "properties": {
        "user": { "$ref": "#/definitions/User" },
        "note": { "type": "string" },
        "lastModifiedDateTime": { "type": "string" }
      }
    },
    "closedDateTime": { "type": "string" },
    "users": {
      "type": "array",
      "items": { "$ref": "#/definitions/User" }
    },
    "participants": {
      "type": "array",
      "items": { "$ref": "#/definitions/User" }
    },
    "lastMessageId": { "type": "string" },
    "createdDateTime": { "type": "string" },
    "lastModifiedDateTime": { "type": "string" }
  },
  "definitions": {
    "ChatSessionStatus": {
      "enum": ["created", "handled", "missed", "completed", "callback"]
    },
    "User": {
      "type": "object",
      "required": ["entityId", "name", "userId", "company"],
      "properties": {
        "entityId": { "type": "number" },
        "name": { "type": "string" },
        "userId": { "type": "string" },
        "company": {
          "type": "object",
          "required": ["entityId", "name", "identifier"],
          "properties": {
            "entityId": { "type": "number" },
            "name": { "type": "string" },
            "identifier": { "type": "string" }
          }
        }
      }
    }
  }
}

Zapier & Webhooks

Below, you can find some steps for an example on how to set up a Webhook with Zapier as a consumer:

1. Sign in to Zapier
2. Create a new Webhook
3. Set the trigger to Catch Hook
4. Save & Continue
   This will generate our Custom Webhook URL! Copy this to your clipboard for later reference.

   

5. Log in to your Admin Portal and head to Advanced > Webhook
6. Paste the trigger URL you received above into the Receiver URL field and fill in the rest of your Webhook's details
7. Save your webhook in DeskDirector

Zapier will now listen for the Webhooks triggered for the Webhook you created in DeskDirector! From Zapier, you can add further logic for filtering and handling what happens when these Webhooks are executed.