Инструкция по работе с веб хуками

Как подключить и протестировать вебхуки

1. Подготовьте адрес приемника

• Используйте только HTTPS-адрес, доступный из интернета.

• Не перенаправляйте запросы на другой URL.

• Отвечайте не дольше 15 секунд.

2. Добавьте endpoint

Укажите URL и понятное название. После создания LeadHunter один раз покажет secret. Сохраните его: повторно посмотреть secret нельзя. При утрате удалите endpoint и создайте новый.

3. Пройдите проверку

После нажатия «Проверить» LeadHunter отправит запрос:

{
  "type": "webhook.endpoint_verification",
  "data": { "challenge": "abc123..." }
}

Верните HTTP 200 и тот же challenge:

{
  "status": "ok",
  "challenge": "abc123..."
}

После успешной проверки endpoint включится и начнёт получать события.

4. Выберите события

Отметьте типы событий на вкладке «События». Запрос события выглядит так:

{
  "id": "…",
  "type": "cabinet.wb.created",
  "version": 1,
  "occurred_at": "2026-08-21T1400+00:00",
  "data": {
    "cabinet_id": "…",
    "cabinet_type": "wb",
    "name": "…",
    "user_id": 123
  }
}

На каждое событие отвечайте HTTP 200 и телом {"status":"ok"}. Иначе доставка будет повторена до пяти раз с нарастающими интервалами в течение примерно девяти часов.

5. Проверьте доставку

1. Подтвердите endpoint и выберите нужные события.

2. На вкладке «Настройки» нажмите «Отправить тест».

3. Убедитесь, что приёмник вернул HTTP 200.

4. Проверьте результат на вкладке «История доставок».

Проверка подписи

Каждый запрос содержит заголовки:

• X-Webhook-Timestamp - время отправки;

• X-Webhook-Signature — HMAC-SHA256 от строки <timestamp>.<сырое тело запроса>, рассчитанный с secret.

Проверка подписи необязательна, но защищает от поддельных событий. Пример для PHP:

$expected = 'sha256=' . hash_hmac(
    'sha256',
    $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] . '.' . file_get_contents('php://input'),
    $secret
);
$valid = hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '');

Минимальный приёмник на PHP

<php?

$rawBody = file_get_contents('php://input') ?: '';
$payload = json_decode($rawBody, true);

$response = ['status' => 'ok'];

// При верификации верните полученный challenge.
if (is_array($payload) && ($payload['type'] ?? '') === 'webhook.endpoint_verification') {
    $response['challenge'] = (string)($payload['data']['challenge'] ?? '');
}

header('Content-Type: application/json; charset=utf-8');
echo json_encode($response);