Входящие вебхуки: получаем данные в ПланФикс без промедления

В ПланФиксе появились вебхуки. Это специальные ссылки, которые нужны для взаимодействия с другими программами и сайтами. Кто впервые слышит о них, не переживайте. Далее объясню, что это такое и для чего.

Что такое вебхуки?

Вебхук — это механизм оповещения одной системы о событиях в другой. Например, на складе товар отгрузили клиенту. Информация об этом из системы складского учета через специальную ссылку поступила в ПланФикс, и в задаче автоматически сменился статус с «Товар отгружается» на «Товар отгружен клиенту». Ссылка, через которую произошло такое взаимодействие двух программ, и называется вебхуком.

Вот пример того, как может выглядеть вебхук в ПланФиксе:

https://ваш_аккаунт.planfix.ru/webhook/get/create_task?project=SEO&name=Провести анализ сайта

Переход по такой ссылке автоматически запустит заранее настроенную операцию: создание задачи в указанном проекте. 

https://ваш_аккаунт.planfix.ru/webhook/get/create_task?project=SEO&name=Провести анализ сайта

Вебхук содержит в себе информацию:

  • о типе запроса (GET или POST),
  • уникальный идентификатор,
  • параметры со значениями.

Вебхуки могут быть двух типов: с GET- или POST-запросом. В чем между ними разница, в каких случаях стоит применять один тип запроса, а в каких другой — подробно расписано в справке. Там же вы найдете примеры применения вебхуков.

В ПланФиксе с помощью входящих вебхуков можно:

  • создавать и изменять задачи,
  • добавлять комментарии,
  • создавать новые контакты.

Как работают вебхуки?

Понять принцип работы вебхуков просто — посмотрите на правила для работы с почтой в ПланФиксе. Вебхуки очень похожи на них. 

Правило почты:

  1. Срабатывает при поступлении письма.
  2. Формирует инфоблоки.
  3. Данными из инфоблоков заполняет поля задач и контактов.

Вебхук:

  1. Срабатывает при переходе по ссылке.
  2. Формирует инфоблоки.
  3. Данными из инфоблоков заполняет поля задач и контактов.

Как видите, между правилами работы с почтой и вебхуками много общего, только источники срабатывания разные.

Как сформировать ссылку вебхука?

Вебхуки настраиваются в разделе «Управление аккаунтом»«Входящие вебхуки»:

Раздел «Входящие вебхуки»
Раздел «Входящие вебхуки».
По клику картинка отроется в большем размере и новом окне.

Разбираться в сложных темах лучше всего на примерах. Поэтому давайте покажу, как организовать в ПланФиксе оценку качества работы сотрудников.

Наш пример:

  1. Клиент обратился в Службу поддержки по e-mail. 
  2. В ПланФиксе появилась новая задача.
  3. Сотрудник Службы поддержки ответил.
  4. Клиент доволен.
  5. Задача перешла в статус «Выполненная».
  6. Клиент автоматически получил сообщение с просьбой оценить работу сотрудника.

Сразу отмечу, этот пример актуален для компаний, клиенты которых ведут переписку через электронную почту.

Этапы настройки:

  1. Добавим в карточку задачи поле типа «Список» с оценками работы сотрудника.
  2. Настроим два вебхука: с положительной и отрицательной оценкой.
  3. Добавим автоматический сценарий, который после изменения статуса задачи будет опрашивать клиента о качестве предоставленных услуг.

Приступим.

Запасайтесь чайком, дальше много текста 🙂

Первый этап: поле «Оценка работы сотрудника»

Добавляем в карточку задачи поле «Оценка работы сотрудника». В нём две оценки – «молодец» и «соленый огурец»:

Поле «Оценка работы сотрудника» типа «Список»
Поле «Оценка работы сотрудника» типа «Список».

Второй этап: настраиваем вебхуки

Нажимаем кнопку «Новый вебхук». Появляется список предустановленных настроек. Для нашего примера я настрою вебхук самостоятельно, поэтому в списке выберу ссылку «Другое»:

Добавляем вебхук в ПланФикс
Добавляем вебхук в ПланФикс.

На первом шаге указываем тип вебхука. Для нашего примера достаточно сформировать простую ссылку с GET-запросом:

Указываем тип вебхука.
Указываем тип вебхука.

На втором шаге добавим параметры, которые надо передавать в ПланФикс. Эта часть настройки вебхука очень похожа на настройку инфоблоков в правилах по разбору почты. Параметр я назвал «Task». А инфоблок, куда будет попадать значение параметра, «Задача»:

Извлекаем данные в инфоблоки
Извлекаем данные в инфоблоки.

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

Идентификатор вебхука
Идентификатор вебхука.

Его можно отредактировать и сделать понятным для человека:

Редактирование идентификатора
Редактирование идентификатора.

На третьем шаге укажем от чьего имени выполнять операции в ПланФиксе:

Указываем от чьего имени выполняется действие
Указываем от чьего имени выполняется действие.
По клику картинка откроется в большем размере и новом окне.

Дальше самое интересное. Настраиваем операции, которые ПланФикс автоматически выполнит, когда клиент перейдет по ссылке:

Настраиваем основную операцию вебхука
Настраиваем основную операцию вебхука.
По клику картинка откроется в большем размере и новом окне.

Тут всё просто. Помните, на втором шаге добавили инфоблок? Сейчас мы говорим ПланФиксу, чтобы он искал задачу с такими же номером, как в инфоблоке. И затем в найденной задаче добавил оценку «Молодец» в поле «Оценка работы сотрудника».

На пятом шаге никаких дополнительных действий не добавляем. А вот на шестом можно указать, куда клиент будет перенаправлен, когда кликнет на ссылку вебхука. Обычно для таких целей используется страница сайта, на которой клиенту сообщается об успешной оценке сотрудника. Тут же укажите и другую страницу, если что-то пойдёт не так:

Ответ на вебхук
Ответ на вебхук.
По клику картинка откроется в большем размере и новом окне.

На этом формирование ссылки вебхука с положительной оценкой завершено. 

Перейдём к вебхуку с отрицательной оценкой сотрудника. Он отличается от предыдущего только тем, что на пятом шаге уведомляем начальника комментарием об отрицательной оценке:

Вебхук для отрицательного отзыва
Вебхук для отрицательного отзыва.
По клику картинка откроется в большем размере и новом окне.

Третий этап: автоматический сценарий опроса клиента

Это завершающий этап настройки. У нас есть поле для оценок и два вебхука. Добавим событие, при котором клиент получит сообщение с просьбой оценить сотрудника.

Я отправлю сообщение клиенту, когда задача-диалог переведена в статус «Выполненная», таким автоматическим сценарием:

Автоматический сценарий отправки опроса клиенту
Автоматический сценарий отправки опроса клиенту.
По клику картинка откроется в большем формате и новом окне.

Обратите внимание на комментарий, который отправляется клиенту. В нём две ссылки. Первая — запустит сценарий выставления положительной оценки, вторая — отрицательной. Тут есть важный момент. Изначально ссылка вебхука, после настройки выглядит так:

https://ваш_аккаунт.planfix.ru/webhook/get/goodjob?task=укажите

Слово «укажите» надо заменить на переменную, например номера задачи, в которой сотрудник работал с клиентом.

Где взять переменную? Нажимаем на ссылку «различные поля» и формируем переменную номера задачи:

Добавляем переменную в вебхук
Добавляем переменную в вебхук.
Переменная для использования
Переменная для использования.

Теперь вебхук с положительной оценкой будет выглядеть так:

https://ваш_аккаунт.planfix.ru/webhook/get/goodjob?task={{Задача.Номер}}

Окончательно сформированную ссылку добавляем в сообщение. Выделяем нужное слово и нажимаем на иконку добавления ссылки:

Добавляем ссылку вебхука в сообщение для клиента
Добавляем ссылку вебхука в сообщение для клиента.
В ссылку вебхука добавляем переменную
В ссылку вебхука добавляем переменную.

Вот что в итоге увидит клиент:

Письмо клиенту с ссылками для оценки
Письмо клиенту с ссылками для оценки.

Клиент кликнет на одну из ссылок, вебхук сработает. Откроется страница сайта с сообщением о благодарности за обратную связь, а в ПланФиксе в выполненной задаче автоматически добавится соответствующая оценка:

Оценка клиента пришла в ПланФикс
Оценка клиента пришла в ПланФикс.

Теперь вы знаете способ, как организовать в ПланФиксе оценку качества работы сотрудников. Всем, кто дочитал до конца, по плюсику в карму 😉

А что дальше?

Если вы всё прочитали, а вам ничего непонятно до сих пор — не переживайте. Вебхуки — это не то, что срочно надо всем сделать. Просто знайте, если в будущем столкнетесь с задачей по настройке оценки работы сотрудников, в блоге ПланФикса вас ждёт готовый алгоритм действий на такой случай. А в справке есть пример того, как получить контактные данные из формы обратной связи на сайте.

В целом, вебхуки находятся на той грани, где заканчивается просто настройка ПланФикса и начинается программирование. Поэтому, если вам что-то кажется сложным и непонятным — это нормально. Зовите программистов и обрадуйте их, что есть возможность отправлять в ПланФикс POST-запросы. И может быть какие-то процессы в вашей работе станут ещё удобнее.


Если остались вопросы — задавайте их нашей Службе поддержки, подписывайтесь на социальные сети: Facebook, ВКонтакте, Telegram, Twitter, YouTube-канал и пользуйтесь вебхуками 😉

24 комментария

  1. Аватар

    Хорошие новости будем тестировать.
    Вот только пока не понятно, когда контакт перейдет по ссылке что он увидит, какую страницу, как она будет выглядеть?
    Также отправляя адрес включающий название аккаунта создаем потенциальную опасность для взлома и посылки спама (хотя конечно это секрет Полишинеля и с свойствах письма из ПФ он все равно есть).
    Пока начнем тестировать POST и разбор JSON формата.

  2. Аватар

    Ребята, классная штука вебхуки. Я настроил один. Но, что делать, когда что-то идёт не так? Есть ли какое-то логирование работы вебхуков? Если с ошибкой вебхук отработал, то где-то это остаётся? У меня такое случилось, и я пока не могу понять, в чём проблема.

    1. Аватар

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

      1. Аватар

        Артём, спасибо за ответ. Я 18 февраля в 10:33 в поддержку написал. Пока не ответил никто, к сожалению.
        Вебхук внешний это. И он не по задаче, а по контакту. Получается я извне вызвал вебхук, который должен был создать контакт. Но, он его не создал. Какой лог смотреть, пока не очень понятно. У несозданного контакта не посмотреть, очевидно…

        Ещё, я посмотрел на лог контакта, созданного через вызов вебхука. Мне кажется, неплохо было бы в логе вебхука показывать, по возможности, сам вызов, который Планфикс получил извне. Может быть, не всем подряд эту информацию показывать надо, конечно. Но, для отладки интеграции чем больше информации, тем лучше. Иначе всегда слышишь сакральную фразу “с нашей стороны пули вылетают…”

        1. Аватар

          Константин, вы не подключили поддержку к задаче. Поэтому сообщения к нам не попали.

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

          1. Аватар

            Артём, да, похоже, что неправильно обращение в поддержку оформил. Создал задачу в проекте Обучение и поддержка. А нужно было обращение. Большой перерыв в использовании сервиса был. Уже забыл как что делается. Создал правильно обращение. Буду признателен за помощь.

    1. Аватар

      Там в пункте 4 (основная операция) есть три опции, что делать с контактом. Можно новый создать, можно обновить существующий, или не обновлять.

  3. Аватар

    А почему не сделали парсинг текста данных вебхука? В вебхук передаю текст комментария, приходящего в задачу. Хочу прям из этого текста парсингом, на подобии реализованного у вас в работе с почтой, растащить информацию по инфоблокам.

    1. Аватар

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

      Касательно парсинга в общем, в планах есть глобальная задача по парсингу комментариев.

      1. Аватар

        Я планирую это использовать для изменения задачи при срабатывании тригера в совершенно не связанной с ней другой задаче. Т.е. пришло изменение в одну задачу, например это ответ комментом на опрос по апи внешней системы. И через данные в этом ответе поиск нужной задачи и ее изменение. Как мне видится это можно сделать только вебхуком, потому как в сценариях я не нашел подбор задачи для изменений с помощью инфы из ее кастомного поля. И не припомню что бы такую возможность анонсировали. Поэтому вы сделали мощный и многофункциональный инструмент, но искусственно ограничили его возможности не введя в него уже разработанный вами парсинг по тексту, который отлично работает в парсинге почты, и с которым у пользователей не должно возникнуть проблем, потому что все уже привыкли при настройках работы с мейлом.

        1. Аватар

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

Добавить комментарий