Вебхуки

Вебхуки (webhooks) — инструмент для оповещения сайтов или сервисов об определённых событиях. Они позволяют отслеживать изменения на Омнидеске и отправлять нужную информацию на указанный вами URL, чтобы выполнять действия на других сервисах. Если предпочитаете видеоформат, можете ознакомиться с кратким руководством по вебхукам тут. 

Примеры использования

Можно выделить две основных схемы использования вебхуков:

1. Выполнение прямого запроса в адрес API того или иного сервиса. Вот некоторые задачи, которые можно решить:

а. У вас есть VIP клиенты. При поступлении входящих обращений от них вы хотите получать не только уведомления на почту, но и SMS;
б. Вы хотите получать уведомления о событиях в обращении в привычный мессенджер;
в. Если обращение помечается определенной меткой, хотите автоматически ставить задачу в Basecamp, JIRA или на любом другом сервисе.
г. Передавать нужные данные в кабинет пользователя на вашем сайте.
д. Выполнить запрос можно и в адрес самого Омнидеска. Например, через вебхук можно создать новое обращение, выставить язык в данных пользователя или выполнить другое доступное в API действие.

2. Отправка данных в адрес вашего скрипта. Скрипт получает данные, обрабатывает их и затем выполняет нужные вам действия как в сторонних сервисах, так и в Омнидеске. Для написания скрипта потребуется привлечь ваших программистов. Они же должны будут подготовить содержание запроса, который будет передавать вебхук в адрес скрипта.

Настройка

Отправка вебхука — одно из возможных действий в правилах. Это действие доступно во всех типах правил — для входящих, изменённых и текущих обращений.

1. При добавлении действия «Выполнить вебхук» первым делом нужно выбрать метод отправки запроса: 

• POST позволяет добавить данные через API стороннего сервиса;

• GET — проверяет состояние или получает данные;

• PUT — обновляет данные;

• DELETE — удаляет данные.

2. Далее указывается URL, на который будет отправлен запрос. Такая ссылка обычно формируется на принимающей стороне — в настройках выбранного вами сервиса или вашими программистами, написавшими скрипт.

3. Если для принятия запроса требуется аутентификация, достаточно отметить чекбокс и выбрать способ аутентификации:

4. При выборе методов POST и PUT появляются дополнительные поля для указания самого запроса и его формата:

• Если вы создаете собственный скрипт, то можете сделать так, чтобы он принимал запрос с любой структурой, поэтому проще всего в таких случаях отправлять стандартный запрос;

• Если же выполняется запрос в адрес какого-то сервиса, то его API явно ждёт его в определенном виде — поэтому нужно отправлять кастомный запрос. Обычно структура и синтаксис такого запроса описаны в API-документации самого сервиса.

Доступные переменные добавляются через ссылку, расположенную справа над полем.

Пример уведомления в Slack

Чтобы было понятнее, как это выглядит вживую, вот правило, которое мы используем для получения уведомлений в Slack:

Просто скопируйте текст нашего кастомного запроса и сэкономьте время :)

{
        "text": "Создано новое обращение № [case_number]: [case_subject]",
        "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "Создано *новое обращение* № <[case_url] | *[case_number]*>"
            }
        },
        {
            "type": "section",
            "fields": [
                {
                    "type": "mrkdwn",
                    "text": "*Отправитель*\n[user_full_name] \n [user_email]"
                },
                {
                    "type": "mrkdwn",
                    "text": "*Группа*\n[case_group]"
                }
            ]
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*[case_subject]:*\n\n[case_description|text]"
            }
        },
        {
            "type": "divider"
        }
    ]
}

Настроенное таким образом уведомление в Slack выглядит так:

Ограничения

1. В час можно выполнить до 3600 вебхуков. Ограничение действует для всего аккаунта, поэтому учитываются вебхуки, настроенные во всех правилах.

2. Если лимит превышен, запрос откладывается и выполняется сразу после обнуления лимита.

3. Статус 2хх свидетельствует об успешном выполнении вебхука. Статус 3хх означает редирект. Если статус не 2хх или 3хх, то возникла проблема:

• 4хх означает, что ошибка постоянная, поэтому мы не пытаемся ещё раз выполнить вебхук;

• 5хх означает, что ошибка временная, и мы повторяем запрос каждые 30 минут, пока он не будет выполнен успешно, но совершаем не более 48 попыток.