Вебхуки

Последние изменения: 15.05.2024

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


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

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

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

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

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

Настройка

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

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

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

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

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

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

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

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

3f7b7cf1c3e6b3e7cf323456a17be800.png

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

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

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

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

29d6fa4d71b973e4d69699bc64123593.png


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

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

e64cb0fca5a97134c5d865d0e4c29d65.png

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

{
        "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 выглядит так:

1f9fa09691683dade60db4603d899f0a.png


Ограничения

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

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

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

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

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

4. Если в ответ на вебхук вы получаете «http code #0», то либо адресат не отвечает, либо вы некорректно отправляете запрос. Чаще всего проблема в лишнем пробеле или переводе строки в поле «URL для отправки запроса». В таком случае также выполняются повторные попытки отправки вебхука каждые 30 минут, пока он не будет выполнен успешно, но выполняется не более 48 попыток.

Видеоруководство

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

Помогла ли вам статья?