Что такое Callback

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

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

Одно слово, три разных разговора

Буквальный перевод callback – «обратный вызов». Но за переводом скрываются разные механизмы. Чтобы понять задачу, нужно уточнить, кто кого вызывает, в какой среде и какой результат ожидается. В техническом задании одно английское слово способно обеспечить несколько дней взаимного недоумения.

Виджет обратного звонка может использовать API и программные callback-функции внутри своей реализации. Но клиент, который нажимает «перезвоните», заказывает телефонный разговор. Подмена смысла особенно мешает, когда в одной задаче одновременно участвуют сайт, CRM и телефония.

Callback-функция не обязана ждать

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

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

В условной форме поиска асинхронный обработчик может показать найденные товары, когда данные готовы. Однако пользователь за время ожидания успел изменить запрос. Если интерфейс без проверки применит старый результат, на экране появятся ответы на уже забытый вопрос. Поэтому важны не только факт вызова, но и актуальность состояния, к которому относится результат.

Callback API в программной библиотеке означает интерфейс, в котором разработчик передает функции для обработки событий или результатов. Его правила определяют аргументы, порядок вызова, передачу ошибок и допустимые возвращаемые значения. Нельзя считать любой callback API системой сетевых уведомлений.

Callback URL: куда сообщить результат

В HTTP-интеграции вместо функции передают адрес, по которому доступен обработчик. Условный сервис подготовки документов принимает задание и сообщает о его завершении запросом на согласованный callback URL. Получателю не нужно непрерывно спрашивать, готов ли результат: сообщение приходит по событию.

Здесь callback URL – адрес, а обработчик – код, который принимает и разбирает запрос. Одного адреса недостаточно. Стороны согласуют HTTP-метод, формат данных, способ проверки отправителя, ожидаемый ответ и правила ошибок. Значение поля с названием callback URL всегда уточняют по документации API: у разных протоколов назначение и порядок вызова могут отличаться.

Вебхук – распространенный способ таких уведомлений: сервис отправляет запрос на зарегистрированный адрес при наступлении события. Слова часто соседствуют, но callback шире и встречается далеко за пределами HTTP. Функция обработки элемента массива не превращается в вебхук оттого, что ее назвали по-английски.

Доставка уведомления еще не означает завершение работы

Условный сервис сообщил, что документ подготовлен. Принимающая система должна связать уведомление с исходным заданием, проверить полномочия отправителя и сохранить результат. Ответ об успешном приеме имеет смысл давать после того, как сообщение надежно принято к обработке по правилам интеграции. Иначе отправитель успокоится раньше, чем данные попадут в работу.

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

Отдельная задача – подлинность сообщения. HTTPS защищает передачу, но сам по себе не доказывает, что к открытому адресу обратился нужный сервис. Проверяют предусмотренную протоколом подпись, токен или другой способ авторизации. Секретные значения не добавляют в открытые журналы, а поля запроса проверяют до изменения бизнес-данных.

Для длинной работы можно надежно сохранить входящее событие в очередь и обрабатывать его отдельно. Тогда нужно следить и за приемом, и за результатом выполнения. Иначе журнал покажет безупречную доставку в аккуратно растущую очередь, которую никто не читает.

Где это видно в Битрикс24

В Битрикс24 приложение может подписаться на событие, например изменение сделки, и зарегистрировать внешний обработчик. Портал отправляет на него POST-запрос через сервер очередей. При интеграции Битрикс24 с внешней системой важно сопоставить событие с нужной записью и проверить результат обмена: получение уведомления и успешное обновление внешнего учета – разные этапы. Для проверки полезны создание тестовой сделки, ее изменение и контролируемая недоступность получателя.

Если уведомление приводит к обновлению той же сделки, следует заранее описать защиту от циклических изменений. Система А исправляет поле в системе Б, система Б уведомляет А, а А снова исправляет поле. Программам есть о чем поговорить, но бизнесу такая переписка редко нужна.

Что записать до начала разработки

• Какое значение callback используется в задаче: функция, сетевой вызов или телефонный звонок
• Какое событие или результат запускает обработчик
• Какие данные и идентификаторы передаются
• Как проверяется отправитель и что считается успешным приемом
• Что произойдет при повторе, задержке, ошибке и недоступности получателя
• Где видны результат обработки и причина сбоя

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