Несколько событий в LINE Webhook: обработка частичного сбоя
Один webhook-запрос LINE Messaging API может содержать несколько событий, в том числе от разных пользователей. Нельзя обрабатывать только events[0], связывать весь запрос с первым отправителем или подтверждать успех после сохранения лишь части событий. Сначала проверьте подпись, затем надёжно сохраните все события и только после этого верните 200. Устраняйте дубликаты по webhookEventId каждого события, чтобы повторная доставка не запускала бизнес-операции заново.
Главное
- Один HTTP-запрос не обязательно соответствует одному событию, пользователю или диалогу.
- Подтверждение относится ко всему запросу, а записи и состояния обработки — к отдельным событиям.
deliveryContext.isRedelivery— диагностический признак, а не ключ дедупликации.- Повторная доставка LINE не заменяет постоянный архив и собственный механизм повторных попыток фоновых задач.
Почему обработка первого события приводит к потерям
В рекомендациях LINE для разработчиков прямо описан случай, когда сообщение пользователя A и событие подписки пользователя B приходят в одном webhook. Справочник Messaging API определяет массив events и содержащиеся в нём объекты.
| Граница | Что она означает | Ошибочное упрощение |
|---|---|---|
| HTTP-запрос | Доставка, которую нужно проверить и подтвердить | Считать успех первого события успехом всего запроса |
| Объект события | Событие со своим типом, источником и ID | Копировать отправителя или поля сообщения первого события в остальные |
Маршрутизируйте каждое событие по его собственным type и source. Событие подписки — не сообщение с отсутствующим текстом. Поле верхнего уровня destination обозначает бота-получателя, а не общего клиента для всех событий.
Пустой массив — отдельный допустимый случай проверки соединения. Он рассмотрен в руководстве по пустому events. Здесь речь о непустом пакете, приём которого может завершиться частично.
Подтверждайте запрос только после сохранения всего пакета
Сначала проверьте x-line-signature по исходному телу запроса и секрету канала, как описано в руководстве LINE по подписи. Разбирайте JSON после проверки. Связывайте запрос с конфигурацией канала, чей секрет использован, а не выбирайте клиента или арендатора по первому событию.
Рекомендуемая схема — таблица входящих событий в базе данных:
- Проверить внешнюю структуру и необходимые идентификаторы каждого события.
- В одной транзакции вставить события с уникальным ключом из локального идентификатора канала и
webhookEventId. - Существующий ключ считать уже принятым. Не сбрасывать состояние обработки существующей записи в начальное.
- Зафиксировать транзакцию до ответа
200. Медленную работу выполнять отдельно, читая зафиксированные записи.
Этот пример JavaScript показывает только границу приёма. inbox.transaction и tx.insertIfAbsent — абстракции приложения, а не методы LINE или SDK. Реализуйте их через настоящую транзакцию и ограничение уникальности. channelKey берётся из доверенной конфигурации обработчика; подпись входных данных уже проверена.
async function acceptVerifiedLineBatch(payload, channelKey, inbox) {
if (!payload || !Array.isArray(payload.events)) {
throw new Error('Invalid events array');
}
for (const event of payload.events) {
if (!event || typeof event.webhookEventId !== 'string' ||
event.webhookEventId.length === 0 ||
typeof event.type !== 'string') {
throw new Error('Invalid event envelope');
}
}
await inbox.transaction(async (tx) => {
for (const event of payload.events) {
await tx.insertIfAbsent(channelKey, event.webhookEventId, event);
}
});
return 200;
}
Это не полноценный HTTP-сервер. Вызывающий код должен отклонять неверные подписи, обрабатывать ошибки разбора и не возвращать успех при ошибке проверки или фиксации транзакции. При временной недоступности хранилища можно выбрать ответ вне диапазона 2xx, например 503. Это решение приложения, а не гарантия восстановления каждого события со стороны LINE.
Не разделяйте запись в таблицу и публикацию в очередь без механизма восстановления. Сбой между ними может оставить подтверждённую работу недоступной для обработчиков. Пусть фоновые процессы читают таблицу напрямую либо используйте транзакционный outbox для отправки задач.
Восстановление без привязки к составу пакета
В руководстве LINE по приёму сообщений указано, что события могут дублироваться; для обнаружения повторов рекомендуется webhookEventId. При повторной доставке ID сохраняется, а deliveryContext.isRedelivery меняется. Не рассчитывайте, что те же события снова придут вместе, и не используйте хеш всего HTTP-тела как бизнес-ключ дедупликации.
Рассмотрим условный пакет из событий A и B:
| Место сбоя | Рекомендуемое поведение |
|---|---|
| Транзакция падает при сохранении B | Откатить новые вставки; не подтверждать успешный приём |
| A уже сохранено предыдущим запросом | Сохранить прежнюю запись A и всё равно принять B |
| Транзакция зафиксирована, но HTTP-ответ потерян | Повторные ID находят существующие строки, не создавая новые задачи |
| Фоновая задача падает после успешного HTTP-ответа | Повторить работу из своей таблицы, не ждать LINE |
| Приходит допустимый, но ещё не поддержанный тип | Сохранить для контролируемого разбора, не отбрасывать соседние события |
Если существующий код фиксирует каждое событие отдельно, сохраняйте уже записанные строки и учитывайте их при повторной доставке. Успех первой вставки не означает завершения всего запроса.
Повторные попытки фонового обработчика требуют отдельной защиты. Обновление CRM или отправка ответа может завершиться успешно до сбоя при записи результата. Сохраняйте неопределённые исходы и используйте документированную идемпотентность downstream-системы, если она доступна. Для ответов руководство по восстановлению reply token объясняет, почему повтор события не создаёт новую независимую возможность отправки.
Не смешивайте повторную доставку LINE и контракт UnifyPort
Для повторной доставки LINE функция должна быть включена, а webhook — получить неуспешный ответ. LINE не раскрывает число попыток и интервалы и прямо не гарантирует надёжную доставку через этот механизм. Порядок получения также может отличаться от порядка возникновения событий. Сохраняйте timestamp для контекста; позиция в массиве не является глобальным порядком.
Неофициальный интерфейс UnifyPort — отдельный путь для подключённого аккаунта обмена сообщениями. Его стандартная оболочка события содержит id, type, provider, account_id, occurred_at и data, а не массив LINE events. В контракте доставки используется X-Device-Signature при настроенном signing_secret, а любой ответ 2xx подтверждает доставку.
Можно переиспользовать архитектуру надёжного приёма, но не парсер и не подписываемую строку. Отсутствие events не превращает запрос в проверку с пустым массивом. Если требуется именно LINE Official Account, оставайтесь на официальном Messaging API: смена интеграции не восстанавливает частично принятый запрос.
Частые вопросы
Можно вернуть успех, если одно событие завершилось ошибкой?
Только если все события уже надёжно сохранены, а ошибка относится к последующей обработке, которую ваша система умеет восстановить. Если часть событий не сохранена, не подтверждайте успешный приём всего запроса.
Нужно отбрасывать всё с isRedelivery?
Нет. Это может быть первая копия, которую удалось успешно получить. Проверяйте постоянную запись дедупликации.
Делает ли Promise.all обработку пакета безопасной?
Нет. Параллельные операции тоже могут завершиться частично. Безопасность обеспечивают надёжное сохранение, уникальные ключи и правила восстановления, а не способ планирования JavaScript-задач.
Следующий шаг и источники
Проверьте пакет от разных пользователей, сочетание старого и нового события, ошибку фиксации, потерянное подтверждение и сбой фонового обработчика. Это предлагаемые тесты, а не результаты уже выполненной проверки. Для отдельного приёмника UnifyPort начните со справочника доставки webhook.
Официальные источники проверены 2026-11-13:
Превратите интеграцию сообщений в стабильный продуктовый pipeline.
Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.