Опубликовано 1 Июль, 2021 | Лид-формы | 5 165 просмотров | 1 минут уйдет на чтение

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

Как включить вебхуки

1. Открыть настройки блока "Лид-форма"
2. Включить флажок «Отправить вебхук» на вкладках "Действия после заполнения формы" и\или "Действия после оплаты"
3. Указать URL-адрес вебхука
4. Сохранить изменения

 

Структура вебхуков после отправки формы

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

После заполнения формы мы отправим POST-запрос с телом в формате JSON:

{
  "action": "form.submit",
  "info": {
    "form_owner_id": "1",
    "form_owner_email": "owner@mail.ru",
    "form_page_url": "https://linkrr.ru/urpage",
    "form_block_id": "8199",
    "lead_id": "55"
  },
  "data": {
    "name": "pavel",
    "email": "buyer@mail.ru",
    "phone": "+79501232323",
    "fields": {
      "Ваше имя": "pavel",
      "Ваш E-mail": "buyer@mail.ru",
      "Ваш номер телефона": "+79501232323",
      "Какое-то поле": "какие-то данные"
    }
  },
  "sign": "34699a5637e5f4a23f6ab66687ba41d92ccaea0539b6bedfe2faed66384ad680"
}

Объект Info (информация) — общие данные по форме, странице и лиду.

Объект Data (данные) — данные из полей формы, которые заполнил пользователь.

 

Структура вебхуков после подтверждения оплаты

Пример вебхука после оплаты через Продамус:

{
  "action": "form.pay",
  "status": "success",
  "info": {
    "form_owner_id": "123",
    "form_owner_email": "owner@email.com",
    "form_block_id": "321",
    "lead_id": "111",
    "lead_name": "Ivan Ivanov",
    "lead_phone": "+79001231212",
    "lead_email": "lead@email.com"
  },
  "data": {
    "payment_system": "prodamus",
    "amount": "2490.00",
    "fields": {
      "field_id1": "some_data"
    },
    "payload": {
      "date": "2023-09-07T19:34:16+03:00",
      "order_id": "123",
      "order_num": "333",
      "domain": "somedomain.payform.ru",
      "sum": "2490.00",
      "currency": "rub",
      "customer_phone": "+79001231212",
      "customer_email": "lead@email.com",
      "customer_extra": "",
      "payment_type": "Оплата картой, выпущенной в РФ",
      "commission": "3.5",
      "commission_sum": "87.15",
      "attempt": "1",
      "_param_url_query": "",
      "sys": "linkrr",
      "products": [
        {
          "name": "Имя продукта",
          "price": "2490.00",
          "quantity": "1",
          "sum": "2490.00"
        }
      ],
      "payment_status": "success",
      "payment_status_description": "Успешная оплата",
      "payment_init": "manual"
    }
  },
  "sign": "21b64610b023bf933464370a93517ef6b1d9cf683bf5f6b560334"
}

В зависимости от платежного сервиса, структура данных в объекте payload (полезная нагрузка) будет отличаться. Остальные поля будут одинаковые для всех сервисов.

 

Валидация подписи

Если вам нужно проверить источник вебхука и исключить риск подделки запросов, вы можете реализовать проверку подписи в поле sign (подпись).

Подпись формируется из тела (body) запроса по алгоритму HMAC SHA-256.

Пример на PHP, как провести валидацию.

// Шаг 1: Получение данных вебхука
$receivedData = json_decode(file_get_contents('php://input'), true);

// Шаг 2: Извлечение подписи из полученных данных
$receivedSignature = $receivedData['sign'];
unset($receivedData['sign']); // Удаление подписи из данных для последующей проверки

// Шаг 3: Указание вашего API ключа (берется в настройках аккаунта)
$apiKey = 'Ваш_API_ключ';

// Шаг 4: Проверка подписи с использованием метода verify класса Hmac
$isValid = Hmac::verify($receivedData, $apiKey, $receivedSignature);

// Шаг 5: Обработка результата
if ($isValid) {
    // Подпись верна: источник подтвержден
    // Здесь ваш код для обработки данных вебхука
} else {
    // Подпись неверна: источник не подтвержден
    // Здесь ваш код для обработки ситуации неверной подписи
}

 

Класс Hmac на PHP для проверки подлинности запроса

<?php
class Hmac {
    static function create($data, $key, $algo = 'sha256') {
        if (!in_array($algo, hash_algos()))
            return false;
        $data = (array) $data;
        array_walk_recursive($data, function(&$v){
            $v = strval($v);
        });
        self::_sort($data);
        if (version_compare(PHP_VERSION, '5.4.0', '<')) {
            $data = preg_replace_callback('/((\\\u[01-9a-fA-F]{4})+)/', function ($matches) {
                return json_decode('"'.$matches[1].'"');
            }, json_encode($data));
        }
        else {
            $data = json_encode($data, JSON_UNESCAPED_UNICODE);
        }
        return hash_hmac($algo, $data, $key);
    }
 
    static function verify($data, $key, $sign, $algo = 'sha256') {
        $_sign = self::create($data, $key, $algo);
        return ($_sign && (strtolower($_sign) == strtolower($sign)));
    }
 
    static private function _sort(&$data) {
        ksort($data, SORT_REGULAR);
        foreach ($data as &$arr)
            is_array($arr) && self::_sort($arr);
    }
}
?>

 

 

Повторы вебхуков

При отправке запроса информация считается принятой, если в заголовке HTTP-ответа будет возвращён код от 100 до 299, согласно таблице кодов состояния HTTP (w3.org).

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

Таймаут запроса 5 секунд при первой попытке и 10 секунд при последующих

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

 

Номер попытки	Время, прошедшее с предыдущей попытки
1	1 минута
2	5 минут
3	15 минут
4	15 минут
5	1 час
6	1 час
7	2 часа
8	2 часа
9	4 часа

 

После этого запрос будет удалён из очереди, даже если доставка так и не состоялась.