Обслуживание webhook: остановить обработчики, отключить или удалить endpoint?

Если обслуживание затрагивает только downstream-системы, оставьте проверку и надежное сохранение webhook-событий работающими, а остановите обработчики очереди. Отключение endpoint в UnifyPort переводит его в inactive, сохраняя конфигурацию; удаление убирает сам ресурс. Ни одна из этих операций не описана как «пауза с последующей доставкой пропущенного». Выбирайте действие по тому, какой слой должен остановиться.

Главное

• Для обслуживания CRM, AI-процесса или обработчика приостанавливайте бизнес-обработку после надежного приема событий.
• Отключайте endpoint осознанно, с планом действий на случай пробела в доставке.
• Удаление предназначено для вывода endpoint из эксплуатации, а не для обычного развертывания.
• Ответ 503 не создает окно обслуживания: UnifyPort повторяет доставку немедленно, без задержек.

Сравнение трех вариантов

Первая строка — рекомендация по архитектуре приложения. Две другие — документированные операции управления UnifyPort.

Действие	Что меняется	Что остается вашей ответственностью
Остановить обработчики приложения	Потребители не обрабатывают задания; исправный приемник продолжает сохранять события	Емкость очереди, сроки хранения, контрольные точки и идемпотентность действий
Отключить endpoint	Статус становится inactive, ресурс сохраняется	Учет перерыва, проверка повторного включения, расследование пропусков
Удалить endpoint	Ресурс удаляется	Создание и проверка нового endpoint, если он снова понадобится

Справочник отключения endpoint описывает POST /v1/webhook-endpoints/{endpoint_id}/deactivate. Справочник удаления описывает DELETE /v1/webhook-endpoints/{endpoint_id} с ответом 204 No Content при успехе.

Эти действия относятся к webhook endpoint. Они не означают выход из аккаунта, остановку runtime или отмену работы, уже принятой приложением. Обработчик, который успел получить задание, может завершить его. Для прекращения таких действий нужны отдельные средства управления приложением.

Когда лучше остановить обработчики

Предположим, нужно обновить интеграцию с CRM, сохранив прием обращений из LINE и WhatsApp. Это пример архитектуры, а не история клиента или отчет о достигнутом результате.

Отделите прием событий от CRM:

1. Проверьте подпись и временную метку по исходным байтам запроса.
2. Проверьте событие и зафиксируйте его в надежном хранилище.
3. Верните успешное подтверждение.
4. Поручите отдельным обработчикам запись в CRM, обращения к AI и уведомления.

До остановки потребителей убедитесь, что хранилище приема будет доступно весь период работ. Задайте эксплуатационные ограничения на рост очереди и срок хранения, назначьте ответственного за ошибки записи. Массив в памяти не является буфером, способным пережить перезапуск процесса.

После развертывания продолжайте с зафиксированного состояния обработки. Нельзя объявлять весь накопившийся объем завершенным только потому, что входной сервис возвращал 2xx. Чек-лист webhook-first интеграции объясняет границу первоначального сохранения; обслуживание добавляет отдельное управление разрешением на выполнение заданий.

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

Почему ответы с ошибкой не заменяют паузу

По контракту доставки ошибки соединения и ответы 408, 429, 5xx повторяются немедленно. retry_policy.max_attempts задает число повторов после первого запроса; по умолчанию их три. Задержки между повторами нет, Retry-After не учитывается. Другие ответы 4xx останавливают автоматическую доставку и помечают событие как dead-lettered.

Поэтому постоянный 503 во время развертывания может исчерпать попытки, а не отложить их до готовности сервиса. Возвращать 200, отбрасывая содержимое, еще хуже: вы подтверждаете данные, которые не сохранили. Статус dead-lettered также не обещает доступной публичной операции повторной доставки.

Не отключайте проверку подписи на время работ. Пустой signing_secret отключает подпись, а не доставку. Если требуется сменить секрет, используйте отдельную процедуру ротации секрета webhook, не объединяя изменение аутентификации с выводом endpoint из эксплуатации.

Условия восстановления после намеренного отключения

Перед изменением прочитайте конфигурацию endpoint и сохраните его ID, URL, статус, подписки, состояние подписи и политику повторов. Сам секрет должен оставаться в защищенной конфигурации, а не в журнале изменений. Перечислите зависимые downstream-процессы.

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

Для возобновления используйте обновление endpoint с status: active и проверенной конфигурацией. Сохраните нужные URL, подписки, политику повторов и непустой секрет подписи. Не переносите в production демонстрационные настройки с неактивным статусом или отключенной подписью.

Прочитайте результат, убедитесь в signing_enabled: true и отправьте контролируемое тестовое сообщение на подключенный messaging-аккаунт. Проследите событие message.received через проверку подписи, надежное сохранение и нужный обработчик. Это подтверждает работу нового пути доставки, но не восстановление неактивного периода.

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

Удаление и границы восстановления

Удаляйте ресурс только после решения о его ненужности и проверки зависимостей. Успешный ответ удаления не содержит JSON для разбора. Создание замены позже — новое развертывание, а не восстановление пропущенных доставок старого endpoint.

Неофициальный интерфейс UnifyPort нормализует поддерживаемые события messaging-аккаунтов, но не предоставляет универсальный REST API чтения истории сообщений и не гарантирует повторную доставку пропущенных данных. Ограниченные механизмы истории WhatsApp не являются гарантией восстановления после обслуживания для всех каналов.

При продолжении сохраненных заданий соблюдайте документированные границы дедупликации: повторы обычных событий используют тот же X-Device-Event-Id; пакеты conversation.history требуют объединения по сообщениям, а не глобального исключения по одному этому заголовку. Идемпотентность исходящих бизнес-действий обеспечивайте отдельно.

FAQ

Сохраняется ли endpoint после отключения?

Да. Статус становится inactive, ресурс не удаляется. Но это не гарантия хранения накопившихся событий или их повторной доставки.

Можно остановить только AI-процесс?

Да, на уровне архитектуры приложения: остановите соответствующего потребителя, сохранив проверку и надежный прием событий. Это не дополнительный параметр API UnifyPort.

Стоит ли удалять и создавать endpoint при каждом развертывании?

Обычно нет. Для downstream-работ останавливайте потребителей; при необходимости перерыва в работе endpoint планируйте его явно. Удаление — решение о выводе из эксплуатации.

Следующий шаг и источники

Изучите контракт доставки и определите, какой слой останавливают ваши работы, прежде чем менять production-конфигурацию.

Документация продукта проверена 2026-10-06:

• Отключение webhook endpoint
• Обновление webhook endpoint
• Удаление webhook endpoint
• Доставка, подтверждения и повторы