Отладка вебхуков Битрикс24: как перестать гадать и начать видеть реальные данные

Разработка интеграций часто превращается в «стрельбу вслепую»: вы меняете код, ждете события в Битрикс24, но ничего не происходит. В этой статье мы разберем профессиональный подход к отладке: от настройки туннелей для локальной разработки до создания систем глубокого логирования входящих запросов.

Почему вебхуки «не работают»?

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

Проблема доступности: Ваш локальный сервер (localhost) недоступен из интернета, поэтому облачный Битрикс24 просто не может достучаться до вашего эндпоинта.
Ошибка в протоколе: Битрикс24 требует HTTPS. Если ваш сервер работает только по HTTP, запрос может быть заблокирован.
Некорректный ответ: Ваш сервер не вернул 200 OK вовремя или вернул ошибку, из-за чего Битрикс считает доставку неудачной.
Скрытые ошибки в Payload: Структура JSON изменилась или пришло поле, которое ваш код не ожидает, вызывая фатальную ошибку (Exception).

Инструментарий: Ngrok для локальной разработки

Чтобы не деплоить код на боевой сервер ради каждой мелкой правки, используйте Ngrok. Он создает временный публичный URL, который перенаправляет трафик прямо на ваш локальный компьютер.

Как это работает

Вы запускаете Ngrok на своем компьютере, он дает вам адрес вида https://random-id.ngrok-free.app. Этот адрес вы вставляете в настройки исходящего вебхука в Битрикс24. Теперь все события из облака будут прилетать к вам в VS Code или PhpStorm.

Команда для запуска

ngrok http 80

(где 80 — порт вашего локального веб-сервера)

Создание «Дампера»: записываем всё, что прилетает

Если стандартных логов сервера недостаточно, напишите свой «дампер». Это максимально простой скрипт, задача которого — не обрабатывать данные, а просто сохранить их в файл в максимально сыром виде. Это ваш «черный ящик» для анализа.

Вариант 1: PHP Dump (идеально для быстрого теста)

<?php
/**
- Скрипт-дампер для отладки вебхуков Битрикс24
*/

// 1. Получаем все данные запроса
$method = $_SERVER['REQUEST_METHOD'];
$headers = getallheaders();
$body = file_get_contents('php://input');
$ip = $_SERVER['REMOTE_ADDR'];
$timestamp = date('Y-m-d H:i:s');

// 2. Формируем детальный отчет
$logEntry = "=== NEW REQUEST [$timestamp] ===
";
$logEntry .= "IP: $ip | Method: $method
";
logEntry .= "HEADERS:n" . print_r(headers, true) . "
";
logEntry .= "BODY:nbody
";
$logEntry .= "=================================

";

// 3. Записываем в файл
file_put_contents('bitrix_dump.log', $logEntry, FILE_APPEND);

// 4. ВСЕГДА отвечаем 200 OK
http_response_code(200);
echo "Dump successful";
?>

Вариант 2: Python Dump (Flask)

from flask import Flask, request
import datetime
import json

app = Flask([b]name[/b])

@app.route('/debug-webhook', methods=['POST'])
def debug_dump():
    # Собираем данные
    timestamp = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    headers = dict(request.headers)
    body = request.get_data(as_text=True)
    ip = request.remote_addr

    # Формируем запись
    dump_data = {
        "timestamp": timestamp,
        "ip": ip,
        "headers": headers,
        "body": body
    }

    # Записываем в файл в формате JSON
    with open('bitrix_debug.json', 'a') as f:
        f.write(json.dumps(dump_data) + "
")

    return "OK", 200

if [b]name[/b] == '__main__':
    app.run(port=5000)

Чек-лист: как эффективно проводить отладку

Шаг	Действие
1. Проверка связи	Попробуйте отправить тестовый запрос через Postman. Если он не доходит — проблема в Ngrok или доступах.
2. Анализ структуры	Используйте дампер, чтобы увидеть реальный JSON. Часто поля называются иначе, чем в документации.
3. Изоляция логики	Закомментируйте основную логику, оставив только дампер. Если ошибки исчезли — проблема в вашем коде.
4. Проверка типов	Убедитесь, что вы не пытаетесь работать со строкой как с массивом после декодирования JSON.