Вебхуки (Webhooks) — это механизм обратных вызовов, позволяющий мгновенно реагировать на появление задачи на определенном этапе.

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

1. Написать веб-сервис, который будет обрабатывать запросы Pyrus, и разместить его на своем сервере или в облаке.
2. Создать учетную запись бота и указать в профиле бота URL обработчика.
3. Добавить бота в маршрутизацию формы на соответствующем этапе.

При попадании задачи во входящие боту Pyrus отправит обработчику HTTPS запрос методом POST. На запрос ваш бот должен ответить статусом 2xx в течение 60 секунд после вызова. Если вам необходимо добавить комментарий в задачу, вы можете указать его в теле ответа. Формат комментария описан в запросе POST /tasks/{task-id}/comments.

Пример запроса:

{
  event: "comment",
  access_token: "Dfpb1we4..."
  task_id: 1532,
  user_id: 1725,
  "task": {
    "text": "Budget approval",
    "id": 11611,
    "create_date": "2017-08-17T15:32:11Z",
    "last_modified_date": "2017-08-17T15:32:11Z",
    "author": {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com"
    },
    "responsible": {
      "id": 1245,
      "first_name": "my bot",
      "last_name": "",
      "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
    },
    "participants": [
      {
        "id": 1245,
        "first_name": "my bot",
        "last_name": "",
        "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
      },
      {
        "id": 1731,
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "Bob.Smith@gmail.com"
      }
    ],
    "comments": [
      {
        "id": 13767,
        "create_date": "2017-08-17T15:32:11Z",
        "text": "Budget approval",
        "author": {
          "id": 1731,
          "first_name": "Bob",
          "last_name": "Smith",
          "email": "Bob.Smith@gmail.com"
        },
        "reassigned_to": {
          "id": 1245,
          "first_name": "my bot",
          "last_name": "",
          "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
        },
        "participants_added": [
          {
            "id": 1245,
            "first_name": "my bot",
            "last_name": "",
            "email": bot@4e83a7da-3ba1-4a16-a1d8-21bbd1ad9592
          },
          {
            "id": 1731,
            "first_name": "Bob",
            "last_name": "Smith",
            "email": "Bob.Smith@gmail.com"
          }
        ]
      }
    ]
  }
}

Если сервер бота недоступен или отвечает статусом отличным от 2хх, Pyrus отправит второй запрос через 61 секунду, а затем третий — через 122 секунды. Номер попытки виден в дополнительном заголовке X-Pyrus-Retry запроса. Если за три попытки связаться не удалось, Pyrus отправит новый запрос в следующий раз, когда кто-то прокомментирует задачу.

Заголовки запроса:

• User-Agent. Значение — Pyrus-Bot-4. Здесь цифра 4 – версия протокола (совпадает с версией Pyrus API).
• X-Pyrus-Sig. Значение — строка, содержащая подпись сообщения для проверки того, что вызов бота выполнил Pyrus, а не кто-то другой. Для проверки подписи необходимо к телу запроса добавить секретный ключ и вычислить для получившейся строки HMAC-дайджест с использованием алгоритма SHA1. Смотрите реализацию проверки подписи на Python.
• X-Pyrus-Retry. Значение — одно из трех: «1/3», «2/3» или «3/3». В числителе номер попытки, начиная с единицы, а в знаменателе — количество попыток (три попытки). Для первого вызова, который не является повтором, значение ставится «1/3».

• Создать Pyrus-бота на странице ботов (если у вас уже есть бот для доступа к методам Pyrus API, вы можете использовать его).
• Склонировать стартовое бот-приложение и перейти в его папку:

git clone https://github.com/simplygoodsoftware/heroku-python-bot.git
cd heroku-python-bot

• Прописать Секретный ключ Pyrus-бота в файле конфигурации config.json

{
  "SECRET_KEY": "Bot-Secret-Key"
}

• Создать и запустить Heroku-приложение:

heroku create
git add .
git commit -m "replaced SECRET_KEY in config.json"
git push heroku master
heroku ps:scale web=1

• В настройках Pyrus-бота в поле URL указать полученный в предыдущем шаге URL.
• Назначить задачу в Pyrus на бота. В ней автоматически появится комментарий с ответом бота:

Hello, {user_name}! You said "{comment_text}".