Webhooks — a tool for notifying websites about certain events. They allow you to track changes in Deskie and send the necessary information to the URL you specify in order to perform actions on other services.

Use cases

There are two main schemes for using webhooks:

1. Making a direct request to the API of a particular service. Here are some of the tasks that can be accomplished:

a. You have VIP customers. When you receive a new case from them, in addition to email notifications, you would also like to receive SMS;
b. You want to receive notifications about the events in cases in your familiar messenger;
c. If the case has been marked with a certain label, set the task in Basecamp, JIRA or any other services automatically;
d. Transmit the required data to the user's personal profile on your website;
e. It is also possible to make a request addressed to Deskie itself. For example, a webhook can be used to create a new case, set a language in user data or perform another action available in the API.

2. Sending data to your script. The script receives the data, processes it, and then performs the actions you need, either in third-party services or in Deskie. To write the script you will need to involve your developers. They will also need to prepare the content of the request, which will pass the webhook to the script.

Setup

Sending a webhook is one of the possible actions in rules. This action is available in all rule types — for new, updated and existing cases.

1. When adding  "Send webhook" action, the first step is to choose the method of sending the request:

• POST allows you to add data via a third-party service API;

• GET - checks status or retrieves data;

• PUT - updates data;

• DELETE - deletes data.

2. Next, you specify the URL of the request, to which you can insert variables via a link to the right above the field. This link is usually generated on the receiving end, either in the settings of your chosen service or by your developers who wrote the script.

3. If authentication is required to accept the request, just tick the checkbox and select the authentication method:

4. When selecting the POST and PUT methods, additional fields appear to specify the request itself and its format:

• If you create your own script, you can make it so it accepts requests with any structure, therefore it's easiest to send a standard request in such cases;

• If you are sending a request to a service, its API will accept it in a certain format, hence a custom request has to be sent. Usually the structure and syntax of such a request is described in the API documentation of the service itself.

Example of notification in Slack

To make it clearer what it looks like in real life, here's the rule we use to get notifications about new cases in Slack:

Just copy the text of our custom request and save time :)

{
        "text": "New case № [case_number] created: [case_subject]",
        "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "Created *new case* № <[case_url] | *[case_number]*>"
            }
        },
        {
            "type": "section",
            "fields": [
                {
                    "type": "mrkdwn",
                    "text": "*Sender*\n[user_full_name] \n [user_email]"
                },
                {
                    "type": "mrkdwn",
                    "text": "*Group*\n[case_group]"
                }
            ]
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*[case_subject]:*\n\n[case_description|text]"
            }
        },
        {
            "type": "divider"
        }
    ]
}

A Slack notification set up in this way looks like this:

Limitation

1. You can perform up to 3600 webhooks per hour. The limit applies to the entire account, so webhooks set up in all rules are counted.

2. If the limit is exceeded, the request is postponed and executed immediately after the limit is reset.0

3. A status of 2xx indicates successful execution of the webhook. A status of 3xx indicates a redirect. If the status is not 2xx or 3xx, there is a problem:

• The status 4xx means that the error is permanent, so we don't try to send the webhook again.

• The status 5xx means that the error is temporary, and we repeat the request every 30 minutes until it is successful, but no more than 48 attempts.