Webhook — метод расширения функционала веб-приложения с помощью обратных вызовов (вебхуков). Эти обратные вызовы могут поддерживаться, изменяться и управляться сторонними пользователями и разработчиками, которые не обязательно связаны с исходным приложением.

Настройка

В настройках вы можете указать URL вашего приложения, на который Webhook отправит запрос, когда процесс дойдет до этого элемента. Можно выбрать метод отправки запроса: GET, POST, PUT, PATCH или DELETE.

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

Передаваемые GET- и POST-параметры настраиваются в отдельных блоках. Так, для вашего удобства и минимума ошибок, GET-параметры располагаются один под другим. Для POST-параметров также возможна передача через тело запроса. Для этого выберите «Body» при настройке параметров.

Обработка ответа от сервера

Важная функция элемента — возможность записать ответ от вебхука и заполнить полученным значением локальный параметр процесса. Можно извлечь JSON-данные, HTTP-статус ответа или заголовки. Возможность обработки ответа от сервера не может работать одновременно с функцией "Ждать результат выполнения".

Представим, что в теле ответа на запрос мы получили такой ответ в формате JSON:


"store": {
    "book": [
      { "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95,
        "available": true
      },
      { "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99,
        "available": false
      },
      { "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99,
        "available": true
      },
      { "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99,
        "available": false
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95,
      "available": true
    }
  },
  "authors": [
    "Nigel Rees",
    "Evelyn Waugh",
    "Herman Melville",
    "J. R. R. Tolkien"
  ]
}

Теперь рассмотрим примеры, которые позволят извлечь конкретные данные из ответа в формате JSON. Для ключей используется язык запросов JSONPath:

body.store.bicycle.price — Цена велосипеда.
body.store.book[*] — Все книги.
body.store.book[1,3] — Вторая и четвертая книги.
body.store.book[1:3] — Со второй книги по третью.
body.store.book[:3] — С первой книги по третью.
body.store.book[x:y:z] — Книги с x по y с шагом z.
body.book[?(@.category == 'fiction')] — Все книги с категорией художественные.
body.*[?(@.available == true)].price — Цены всех продуктов в наличии.
body.book[?(@.price < 10)].title — Заголовки всех книг дешевле 10.
body.book[?(@.author==body.authors[3])] — Все книги «Дж. Р. Р. Толкина».
body[store] — Магазин.
body.book[*][title, 'category', «author"] — Заголовок, категория и автор всех книг.
body.book[?(@.author in [body.authors[0], body. authors[2]])] — Все книги Найджела Рииса или Германа Мелвилла.
body.store.book[?(@.category == 'fiction' and @.price < 10 or @.color == «red»)].price — Художественные книги и с ценой ниже 10 или книга красного цвета («и» приоритетнее чем «или»).
headers.content-type - В ответах сервера заголовок Content-Type сообщает клиенту, какой будет тип передаваемого контента.
http.status - Часть первой строки ответа сервера при запросах по протоколу HTTP.
http.error - Обозначение причины ответа.

Ждать результат выполнения

В настройках элемента можно включить флажок «Ждать результат выполнения». В этом случае, после отправки данных на ваше приложение, процесс приостановится. Чтобы продолжить работу процесса, необходимо отправить на специальный адрес результат работы Webhook:

https://api.sensei.plus/webhook?result=<result>&hash=<hash>

Где <result> — результат работы. Строковый параметр, значение должно соответствовать результату, указанному в настройках элемента webhooks.

<hash> — хэш-значение, соответствующее запущенному процессу. Данный hash-параметр отправляется вместе с информацией о сделке в заголовке параметром HTTP_X_HASH.

Опционально, есть возможность «Добавить время ожидания». Если результат работы не придёт за период, указанный в настройках, то процесс пойдёт по специальной ветви.

Ниже мы привели сразу 5 примеров использования элемента. Рассмотрим их подробнее:

Пример 1

Мы хотим уведомить стороннее приложение, что сделка дошла до определенного этапа в процессе. Для этого будем отправлять веб-хук на адрес https://domain.ru/myapp.php, без ожидания результата от приложения процессом.

В этом случае настройка веб-хука в процессе будет выглядеть следующим образом:

В приложение myapp. php, которое мы настроили в примере, придет POST-запрос, содержащий данные о сделке. Структура массива с данными идентична структуре webhook’s в amoCRM:


{
    "sensei":
        [
            {
                "id":"118261",
                "name":"Бытовая техника онлайн",
                "date_create":"1545042870",
                "created_user_id":"2368945", 
                "last_modified":"1545135210",
                "price":"1000000",
                "responsible_user_id":"1320969",
                "linked_company_id":"456127",
                "pipeline_id":"1509766",
                "date_close":"0",
                "closest_task":"1545135209",
                "status_id":"23300671"
            }

Пример 2

Настроим второй webhook, который бы ожидал результат от нашего приложения:

Приложение, также как и в первом примере, получит информацию о сделке. Но работа процесса будет приостановлена. Процесс будет возобновлен, когда приложение отправит результат обратно в процесс Сенсея. Результат может быть отправлен сразу или через какое-то время.

Рассмотрим для примера, что приложение отправило ответ сразу, чтобы процесс продвинулся дальше:


<?php
// получаем информацию о сделке
$lead = $_POST['sensei'][0];
// делаем необходимую обработку ...
// и получаем результат работы
$result = 'result1';
// в заголовке запроса также получаем hash-значение, запущенного процесса
$hash = $_SERVER['HTTP_X_HASH'];
// продолжаем работу Сенсея с результатом result1
$link = 'https://api.sensei.plus/webhook?hash='.$hash.'&result='.$result;
$curl = curl_init();
curl_setopt($curl,CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl,CURLOPT_USERAGENT, 'sensei-API-client/1.4');
curl_setopt($curl,CURLOPT_URL, $link);
curl_setopt($curl,CURLOPT_HEADER, false);
$out = curl_exec($curl);
curl_close($curl);

Пример 3

Передача параметров методами GET и POST:

GET-параметры передаются URL после символа «?» по принципу параметр = значение. Разделителем между параметрами выступает символ «&». Для передами POST-параметров потребуется включить флажок «POST-параметры». Элемент поддерживает передачу масок в значениях параметров.

Пример 4

Добавим вебхуку возможность записать полученный ответ в локальный параметр процесса. Отправляем запрос, где указываем параметр, значение которого нужно записать — body.data.user.timezone. Ответ получаем в формате JSON:


{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "johndoe@example.com",
      "phone": "+1234567890",
      "address": "123 Main St, Anytown, USA",
      "timezone": "UTC+3"
    },
    "orders": [
      {
        "id": 1,
        "product": "Product 1",
        "quantity": 2,
        "price": 10.99,
        "status": "completed"
      },
      {
        "id": 2,
        "product": "Product 2",
        "quantity": 1,
        "price": 19.99,
        "status": "pending"
      }
    ]
  }
}

В локальный параметр запишется значение UTC+3.

Пример 5

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


$localParams = [
    'name1' => ‘valeu1’,
    'name2' => ‘value2’
];
senseiSend($result, $localParams);
function senseiSend($result, $localParams = [])
{
    $hash = $_SERVER['HTTP_X_HASH'];
    $body = [
        'params' => [
            'local' => $localParams
        ]
    ];
    $body = json_encode($body);
    $link = 'https://api.sensei.plus/webhook?hash=' . $hash . '&result=' . $result;
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_USERAGENT, 'sensei-API-client/1.4');
    curl_setopt($curl, CURLOPT_URL, $link);
    curl_setopt($curl, CURLOPT_HEADER, false);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
    $out = curl_exec($curl);
    curl_close($curl);
}

Пример 6

Создадим процесс, который будет проверять, успешно ли сервер обработал наш webhook.

Для этого создадим локальный параметр «Статус ответа», куда позже будем записывать статус ответа от сервера. В настройках элемента добавим в поле URL ссылку на хук, и настроим запись http-статуса в указанный параметр.

Проверять успешность записи ответа будем через элемент «Условие». В случае, если ответ от сервера не будет «успешным» процесс пройдет по ветке «Нет» и уведомит ответственного сотрудника в Telegram.

Если ответ от сервера не будет получен вовсе, то элемент отправит хук повторно через 10 секунд. После чего элемент в течение 60 секунд ждёт ответ и останавливает процесс, если ответ так и не был получен. В случае успешной второй попытки, элемент будет считаться выполненным и в данном примере условие пройдет по ветке «Да».

Что ещё почитать:

Private виджеты