Published on 1 July, 2021 | Лид-формы | 3,050 views | 1 minutes read

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

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

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

 

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

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

После заполнения формы мы пошлем POST запрос с json body:

{
  "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": "onwer@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 sha256.

Пример на 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, согласно таблице кодов статусов w3.org.

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

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

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

 

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

 

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