Как проверить свой обработчик для обработки событий Битрикс24

Тестовый обработчик помогает проверить, что Битрикс24 может отправить событие на ваш сервер, а сервер принимает и сохраняет данные события. Для проверки не нужно ждать реального действия в Битрикс24: событие ONAPPTEST вызывается вручную методом event.test.

Результат сценария — файл в папке log на вашем сервере с телом POST-запроса от Битрикс24: кодом события, переданными данными и блоком auth.

Методы сценарияМетоды сценария

Сценарий состоит из пяти шагов:

1. Создать файл handler.php, который сохраняет входящий запрос в файл
2. Зарегистрировать обработчик события ONAPPTEST методом event.bind
3. Вызвать тестовое событие методом event.test
4. Проверить, что в папке log появился файл с данными события
5. Удалить тестовый обработчик методом event.unbind

Что понадобитсяЧто понадобится

• приложение с авторизацией OAuth 2.0. Методы event.bind и event.test работают только с этим типом авторизации, входящий вебхук их вызвать не может
• токен доступа OAuth для вызова методов. Дополнительный scope не нужен: event.bind, event.test и событие ONAPPTEST относятся к базовым
• публичный URL обработчика по протоколу http или https, доступный из внешней сети. Битрикс24 проверяет URL при регистрации: адрес должен содержать доменное имя с точкой, поэтому localhost и IP-адрес без домена не подойдут
• файл handler.php на вашем сервере и папка log рядом с ним, доступная веб-серверу для записи
• завершенная установка приложения. Пока установка не завершена, события в приложение не отправляются, хотя event.bind и event.test отвечают успешно. Проверьте установку приложения

Подготовьте обработчикПодготовьте обработчик

Создайте файл handler.php на сервере и убедитесь, что он открывается по публичному URL. Код сохраняет входящий запрос в отдельный файл и при первом запуске сам создает папку log.

Как использовать примеры в документации

<?php
$logDir = __DIR__ . '/log';

if (!is_dir($logDir)) {
    mkdir($logDir, 0775, true);
}

file_put_contents(
    $logDir . '/' . uniqid((string)time() . '-') . '.txt',
    var_export($_REQUEST, true)
);

Битрикс24 отправляет событие POST-запросом, поэтому данные окажутся в $_REQUEST. Имя файла складывается из времени запроса и случайного суффикса, поэтому каждое событие попадет в отдельный файл даже при нескольких срабатываниях в одну секунду.

Зарегистрируйте тестовое событиеЗарегистрируйте тестовое событие

Зарегистрируйте событие ONAPPTEST методом event.bind. В параметре handler передайте публичный URL файла handler.php.

Замените значения в примерах:

• https://example.com/handler.php — на URL вашего обработчика
• **put_access_token_here** — на токен доступа OAuth
• **put_your_bitrix24_address** — на адрес вашего Битрикс24

Вкладки с SDK рассчитаны на уже созданный клиент. Как его инициализировать, описано в разделе SDK для разработки под Битрикс24.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"event":"ONAPPTEST","handler":"https://example.com/handler.php","auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/event.bind

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<boolean>({
    method: 'event.bind',
    params: {
      event: 'ONAPPTEST',
      handler: 'https://example.com/handler.php',
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('event.bind result:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function bindEvent() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'event.bind',
        params: {
          event: 'ONAPPTEST',
          handler: 'https://example.com/handler.php',
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('event.bind result:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', bindEvent)
</script>

require_once('crest.php');

$eventBind = CRest::call(
    'event.bind',
    [
        'event' => 'ONAPPTEST',
        'handler' => 'https://example.com/handler.php'
    ]
);

if ($eventBind['result']) {
    echo 'event bind successful';
}

// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "event.bind", b24.Params{
	"event":   "ONAPPTEST",
	"handler": "https://example.com/handler.php",
})
if err != nil {
	return fmt.Errorf("event.bind: %w", err)
}

var ok bool
if err := json.Unmarshal(res.Result, &ok); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("выполнено:", ok)

Успешная регистрация возвращает true.

{
    "result": true
}

Вызовите тестовое событиеВызовите тестовое событие

Вызовите метод event.test с произвольными данными. Битрикс24 отправит событие ONAPPTEST на URL, который вы указали при регистрации обработчика.

В примере параметр any со значением data используется как тестовое значение. Метод не проверяет состав параметров: любые переданные пары «ключ — значение» вернутся в обработчик внутри data.QUERY. По ним вы и убедитесь, что до сервера дошел именно ваш вызов.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"any":"data","auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/event.test

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<number>({
    method: 'event.test',
    params: {
      any: 'data',
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('event.test result:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function testEvent() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'event.test',
        params: {
          any: 'data',
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('event.test result:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', testEvent)
</script>

require_once('crest.php');

$result = CRest::call(
    'event.test',
    [
        'any' => 'data'
    ]
);

if ($result['result']) {
    echo 'successful';
}

// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "event.test", b24.Params{
	"any": "data",
})
if err != nil {
	return fmt.Errorf("event.test: %w", err)
}

var value int
if err := json.Unmarshal(res.Result, &value); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("результат:", value)

Успешный вызов метода event.test возвращает 1. Ответ подтверждает только то, что Битрикс24 принял вызов и поставил событие в очередь, — доставку до сервера проверяйте по файлу в папке log.

{
    "result": 1
}

Проверим результатПроверим результат

Откройте папку log рядом с файлом handler.php. При успешном выполнении сценария в ней появится файл с данными события.

Содержимое файла — результат var_export, а не исполняемый код. Блок auth в примере свернут, его ключи разобраны в статье Параметр auth.

array (
    'event' => 'ONAPPTEST',
    'event_handler_id' => '1',
    'data' =>
    array (
        'QUERY' =>
        array (
            'any' => 'data',
        ),
        'LANGUAGE_ID' => 'ru',
    ),
    'ts' => '1573120286',
    'auth' => array (...),
)

Сверьте ключи файла с тем, что вы отправляли:

Если файл создан и содержит data.QUERY.any, обработчик доступен из Битрикс24 и принимает данные событий. Тем же способом можно проверять обработчики реальных событий: замените ONAPPTEST на нужный код события и выполните в Битрикс24 действие, которое его запускает.

Ошибки и диагностикаОшибки и диагностика

Если любой из методов сценария вернул ошибку, найдите ее код в таблице. Коды WRONG_AUTH_TYPE и expired_token относятся ко всем трем вызовам, остальные — к event.bind.

Если метод event.bind вернул true и метод event.test вернул 1, но файл в папке log не появился, проверьте по порядку:

• подождите несколько секунд и обновите папку. Событие уходит через очередь, поэтому приходит не мгновенно
• установка приложения завершена. Пока она не завершена, оба метода отвечают успешно, но события в приложение не отправляются
• URL handler открывается из внешней сети, а не только из вашей локальной сети
• сервер принимает POST-запросы на файл handler.php и не отвечает редиректом
• папка log существует рядом с файлом handler.php, а у веб-сервера есть права на запись в нее
• в коде обработчика нет ошибок PHP — проверьте лог ошибок веб-сервера

После каждой правки повторяйте сценарий с вызова event.test — заново регистрировать обработчик не нужно.

Если Битрикс24 развернут в закрытом контуре, обработчику может мешать сетевая политика. Проверьте доступы по статье Необходимые сетевые доступы.

Удалите тестовый обработчикУдалите тестовый обработчик

После проверки удалите подписку, чтобы тестовое событие не уходило на ваш сервер. Передайте в event.unbind те же event и handler, что и при регистрации.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"event":"ONAPPTEST","handler":"https://example.com/handler.php","auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/event.unbind

В ответе count — число удаленных обработчиков. Значение 0 означает, что подписки с такой парой «событие — URL» не нашлось.

{
    "result": {
        "count": 1
    }
}

Что важно учитыватьЧто важно учитывать

Метод event.test проверяет только доставку тестового события ONAPPTEST. Для рабочих событий используйте коды событий из списка, который возвращает метод events, и регистрируйте их методом event.bind.

В рабочем обработчике вместо записи всего запроса проверяйте application_token — так вы убедитесь, что событие пришло от Битрикс24. Как это делать, описано в статье Безопасность в обработчиках.

Продолжите изучениеПродолжите изучение

• События: обзор методов и событий
• Зарегистрировать новый обработчик события event.bind
• Получить список доступных событий events
• Получить список зарегистрированных обработчиков событий event.get
• Отменить зарегистрированный обработчик события event.unbind
• Безопасность в обработчиках