Webhooks

Introduction

Webhooks are a powerful resource that you can use to automate your use cases and improve your productivity.

Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when, for example, a new request occurs.

Use cases

Typical use case for webhook integration is connecting Tiledesk to external CRM, marketing automation tools or data analytics platforms.

Follow this tutorial if you’re developing a Tiledesk integration that reacts to internal Tiledesk events, such as new incoming chat or queued visitor.

For instance, if you’re integrating a marketing automation tool, you could add a new contact every time a Tiledesk visitor starts a chat.

Getting started

To use this tool you need to have basic knowledge about webhooks and Tiledesk authorization protocol.

This tutorial will not be helpful for integrations that pull data on demand (not in reaction to some Tiledesk event). If you just want to pull Tiledesk reports on user request, use the REST API: https://github.com/Tiledesk/tiledesk-docs/tree/de753b1eae5570e317666d2bdce2edd992d506a9/apis/api/README.md

Prerequisites

You’ll need a Tiledesk Account. Sign up to the Tiledesk Dashboard to create a new account: https://panel.tiledesk.com/v3/dashboard

RESTHooks

Tiledesk uses RestHook patterns. REST Hooks itself is not a specification; it is a collection of patterns that treat webhooks like subscriptions. These subscriptions are manipulated via a REST API just like any other resource. More info about Rest Hook here: http://resthooks.org/

Tiledesk can send notifications when some particular action is performed. Such a notification is called a webhook – it’s just a simple HTTP request that Tiledesk sends to your server when a particular event occurs.

To use RestHook you can:

• Create a New Subscription using Dashboard UI. Go to Settings > Project Settings > Developer (tab) and click on Manage WebHook button.

• Create a New Subscription using REST API: https://developer.tiledesk.com/apis/webhooks/subscriptions#create-a-new-subscription

Each Subscription consists of the following properties:

• event – determines when the webhook is sent to your web server.

• target – address of your web server the webhook will be sent to.

Webhook format

Each webhook is an HTTP POST request made to the URL that you provide. The request’s POST body contains webhook information in JSON format.

{
  "hook": {
    "_id": "5c4f1c2e081bde0016cd61d4",
    "updatedAt": "2019-01-28T15:13:50.807Z",
    "createdAt": "2019-01-28T15:13:50.807Z",
    "target": "https://webhook.site/xyzxyz",
    "event": "request.close",
    "id_project": "5ad5bd52c975820014ba9234",
    "createdBy": "5aaa99024c3b110014b478f0",
    "__v": 0
  },
  "timestamp": 1549035233858,
  "payload": {
    "_id": "5c542239721b190016a50538",
    "request_id": "support-group-LXcdORkb1Kp21ucGNEH",
    "requester_id": "5beda319507c7500150b1b80",
    "first_text": "hello",
    "department": "5b8eb4955ca4d300141fb2cc",
    "sourcePage": "http://localhost:4200/#/login",
    "id_project": "5ad5bd52c975820014ba9234"
    ...
  }
}

Each webhook request contains the following properties:

• hook – returns the subscription object that triggered the webhook.

• payload – contains the data of the webhook.

When your server receives a webhook from Tiledesk, it should respond with HTTP 200. Otherwise, Tiledesk will retry sending the webhook to your service for a number of times unless it receives the correct HTTP 200 response.

Note: Tiledesk webhooks are sent with the Content-Type: application/json header, so please make sure your service can handle such requests.

Webhook Models

Webhook events

The following events are available and you can be notified when an action relating to that event occurs. Refer to the linked model for the payload structure.

• request.create — Subscribe to request creations Model: https://developer.tiledesk.com/apis/rest-api/requests#the-request-model

• request.update — Subscribe to requests being updated Model: https://developer.tiledesk.com/apis/rest-api/requests#the-request-model

• request.close — Subscribe to requests being closed Model: https://developer.tiledesk.com/apis/rest-api/requests#the-request-model

• message.create — Subscribe to message creations (sent and receive) Model: https://developer.tiledesk.com/apis/rest-api/messages#the-message-model

• message.create.request.channel.CHANNEL_NAME — Subscribe to messages created from a specific channel, e.g. message.create.request.channel.telegram for Telegram Model: https://developer.tiledesk.com/apis/rest-api/messages#the-message-model

• lead.create — Subscribes to leads creations Model: https://developer.tiledesk.com/apis/rest-api/leads#the-lead-model

• faq.create — Subscribes to FAQ creations Model: https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/rest-api/chat-bots/faq.md#the-faq-model

• faq.update — Subscribes to FAQ updates Model: https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/rest-api/chat-bots/faq.md#the-faq-model

• faq.delete — Subscribes to FAQ deletions Model: https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/rest-api/chat-bots/faq.md#the-faq-model

• faqbot.create — Subscribes to bot creations Model: https://developer.tiledesk.com/apis/rest-api/bots#the-bot-model

• faqbot.update — Subscribes to bot updates Model: https://developer.tiledesk.com/apis/rest-api/bots#the-bot-model

• faqbot.delete — Subscribes to bot deletions Model: https://developer.tiledesk.com/apis/rest-api/bots#the-bot-model

• department.create — Subscribes to department creations Model: https://developer.tiledesk.com/apis/rest-api/management-api/departments#the-department-model

• department.update — Subscribes to department updates Model: https://developer.tiledesk.com/apis/rest-api/management-api/departments#the-department-model

• department.delete — Subscribes to department deletions Model: https://developer.tiledesk.com/apis/rest-api/management-api/departments#the-department-model

• project_user.invite — Subscribes to teammate project invitations Model: https://developer.tiledesk.com/apis/rest-api/team#the-team-model

• project_user.update — Subscribes to teammate updates Model: https://developer.tiledesk.com/apis/rest-api/team#the-team-model

• project_user.delete — Subscribes to teammate project leave Model: https://developer.tiledesk.com/apis/rest-api/team#the-team-model

• group.create — Subscribes to group creations Model: https://developer.tiledesk.com/apis/rest-api/management-api/groups#the-group-model

• group.update — Subscribes to group updates Model: https://developer.tiledesk.com/apis/rest-api/management-api/groups#the-group-model

• group.delete — Subscribes to group deletions Model: https://developer.tiledesk.com/apis/rest-api/management-api/groups#the-group-model

• event.emit — Subscribes to event emitting Model: https://developer.tiledesk.com/apis/rest-api/events#the-event-model

• event.emit.EVENT_NAME — Subscribes to a specific event emitting, e.g. event.emit.typing.start to subscribe to typing indicator events Model: https://developer.tiledesk.com/apis/rest-api/events#the-event-model

• operator.select — Subscribes synchronously to the assignment of the conversation to a specific agent or bot.

  Before Tiledesk assigns a conversation to an operator (agent or bot) you can create a custom endpoint that receives the webhook call and dynamically select the operator based on your custom logic (for example: skills, operating hours, etc.). The webhook sends the following payload: 1) the agents array 2) the available agents array 3) the suggested operator selected by Tiledesk engine if routing is "assigned", while if "pooled" an empty array 4) the department model 5) the project model 6) the id of the operator selected in the previous assignment 7) the conversation in the previous assignment. Attention: only one subscription per project is supported. Example: https://repl.it/@tiledesk/tiledesk-webhook-custom-assignment

Webhook Notification object

A notification object contains the following fields:

• Hook attribute

• Payload attribute

Hook Attribute

Hook attribute contains the subscription object that triggered the webhook.

Attributes:

• _id (string) — The Tiledesk defined id representing the subscription.

• createdAt (timestamp) — The timestamp the subscription was created.

• updatedAt (timestamp) — The timestamp the subscription was updated.

• target (string) — The subscription target URL.

• event (string) — Corresponds to an event, e.g. 'lead.create', 'request.create'.

Payload

Payload is the data associated with the notification. To understand the payload object, consult the model linked in the Webhook Events section for each event type.

Security — Signed Notifications

Each webhook notification is signed by Tiledesk via an x-hook-secret header. This header contains the webhook secret, randomly generated at the first creation (using UI or REST API) of the webhook subscription. Use this header value to verify the notification came from Tiledesk by comparing it with the secret value obtained during the first creation.

Debugging a webhook

If a webhook isn't working correctly, failed invocations will be visible using Get the subscriptions logs REST API: https://developer.tiledesk.com/apis/webhooks/subscriptions#get-the-subscriptions-logs

In most cases, the response comes from the third-party service that receives the webhook request, not Tiledesk itself. You typically need to work with that service to fix errors.

You can use the numeric code in the response status to diagnose issues. These response status codes are standard across HTTP requests. For a list of the standard HTTP response status codes and their meaning, see HTTP response status codes in the MDN web docs.

Note: If a service uses custom HTTP response status codes, you may need to consult their documentation.

Webhook requests have a 10-second timeout. A "Failed: 504 Gateway Timeout" response status indicates a service didn't respond to a webhook's request within this timeout period. The timeout period is not adjustable.

Related

• Previous: NodeJS SDK — https://developer.tiledesk.com/apis/nodejs

• Next: Subscriptions — https://developer.tiledesk.com/apis/webhooks/subscriptions

Last updated 2 years ago

This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the privacy policy: https://tiledesk.com/privacy.html