Как устранить проблемы с вебхуками

Обычно событие происходит, SendPulse через несколько секунд отправляет POST-запрос на ваш URL вебхука, ваш сервер возвращает успешный код, и запрос появляется в журнале с зеленым статусом. Если один из этих шагов нарушается, журнал показывает, какой именно.

Рассмотрим, как устранить проблемы с вебхуками — от сервера, который не получает запросы, до подписи, которая не совпадает.

Содержание

Ваш сервер не получает запросы

Либо SendPulse не отправил запрос, либо ваш сервер его не принял. Журнал запросов показывает, что именно произошло.

Чтобы найти причину, перейдите в Настройки аккаунта > Вебхуки и найдите вебхук. Его карточка должна показывать статус Активный. Если показан Неактивный, нажмите три точки на карточке и выберите Включить.

Нажмите три точки и выберите Редактировать, затем нажмите Тестовый запрос. Зеленая точка с кодом 200 означает, что ваш URL доступен. Если тест завершается ошибкой, читайте раздел Тестовый запрос завершается ошибкой.

Повторите действие, которое вызывает событие.

Нажмите три точки и выберите Журнал, затем нажмите Обновить журнал.

Если записи нет, читайте раздел Событие произошло, но записи в журнале нет.

Если запись показывает ошибку, читайте раздел для ее статуса: Timeout, 4xx или 5xx.

Если запись показывает 200, но ваш сервер не обработал данные, запрос дошел до сервера. Ищите ошибку в своем обработчике и в логах сервера.

Событие произошло, но записи в журнале нет

SendPulse не отправил запрос. Это может произойти по следующим причинам:

событие не выбрано в вебхуке или оно выбрано под другим инструментом, таким как Доставлено под SMS вместо Email;
вебхук неактивен;
действие не вызывает это событие, например, отключение подписчика в адресной книге не является отпиской, поэтому SendPulse не отправляет событие Подписчик отписался;
это был тестовый запрос, а тестовые запросы не отображаются в журнале;
это событие чат-бота или поп-апа, которое раздел Вебхуки не отправляет. Читайте раздел Событий чат-ботов и поп-апов нет в списке.

Чтобы это исправить, нажмите три точки на карточке вебхука и выберите Редактировать. В списке События убедитесь, что событие выбрано под правильным инструментом. Убедитесь, что переключатель Статус включен, и нажмите Сохранить.

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

Если записи все равно нет, обратитесь в службу поддержки и укажите URL вебхука, событие и время действия.

В журнале отображается статус Timeout

SendPulse не получил ответа от вашего сервера вовремя. В столбце Время ответа отображается тире.

Чтобы это исправить, откройте журнал и разверните запись. Секция Тело запроса показывает, что отправил SendPulse. Убедитесь, что ваш сервер доступен из интернета по HTTPS, а его сертификат действителен.

Если на вашем сервере есть файрвол, разрешите IP-адреса из списка IP-адреса источника вебхука в форме вебхука.

Если ваш обработчик долго обрабатывает данные, сначала верните успешный код, а данные обрабатывайте в фоновом режиме.

Нажмите Повторить в строке записи, затем нажмите Обновить журнал.

В журнале отображается статус 4xx

Ваш сервер получил запрос и отклонил его. Распространенные причины следующие:

неправильный путь URL (404);
обработчик, который не принимает POST-запросы (405);
требуется авторизация (401, 403);
фреймворк, который блокирует POST-запросы без токена CSRF (403);
ограничение количества запросов (429).

Чтобы это исправить, разверните запись в журнале. Секция Тело ответа показывает ответ вашего сервера.

Для 404 проверьте путь в поле URL вебхука.

Для 405 сделайте так, чтобы ваш обработчик принимал POST-запросы.

Для 401 или 403 добавьте заголовок авторизации, который ожидает ваш сервер, в секции Дополнительные заголовки или исключите маршрут вебхука из проверок авторизации и CSRF.

Для 429 разрешите больше запросов с адресов из списка IP-адреса источника вебхука.

Нажмите Повторить в строке записи, затем нажмите Обновить журнал.

В журнале отображается статус 5xx

Ваш сервер получил запрос, но не смог его обработать. SendPulse автоматически повторяет запрос через 1, 5 и 30 минут. Каждая попытка — это отдельная запись с ее номером в столбце Попытка, а тело запроса и подпись остаются неизменными.

Чтобы это исправить, разверните запись в журнале. Секция Тело ответа показывает ошибку вашего сервера, а секция Тело запроса показывает, что отправил SendPulse.

Найдите ошибку в логах сервера по времени в столбце Дата и время. Журнал показывает время в часовом поясе вашего аккаунта.

Убедитесь, что ваш обработчик принимает тело каждого выбранного события: набор полей в data отличается от события к событию.

Когда вы исправите ошибку, дождитесь автоматического повтора или нажмите Повторить в строке записи, затем нажмите Обновить журнал.

Тестовый запрос завершается ошибкой

Результат тестового запроса появляется рядом с кнопкой Тестовый запрос: точка, код состояния и время ответа, например, 405 · 87 ms.

Причины те же, что и для обычных запросов, с одним дополнением. Тестовый запрос имеет тип события test, не имеет поля scope и содержит пустое поле data, поэтому обработчик, который ожидает данные события, может завершиться на нем ошибкой.

Чтобы это исправить, сохраните вебхук, нажмите три точки на его карточке, выберите Редактировать и нажмите Тестовый запрос.

Если результат не 200, читайте разделы Timeout, 4xx или 5xx.

Если ваш сервер завершается ошибкой только на тестовом запросе, сделайте так, чтобы обработчик принимал тело без scope и с пустым полем data.

Нажмите Тестовый запрос снова.

SendPulse не принимает URL вебхука

SendPulse поддерживает только публичные HTTPS-URL, и каждый вебхук в аккаунте требует собственного URL. Сообщения валидации для поля URL вебхука следующие:

Сообщение	Причина	Что делать
Введите действительный HTTPS-URL	URL начинается с `http://` или не является действительным адресом.	Введите URL, который начинается с `https://`.
Введите действительный публичный HTTPS-URL	URL указывает на `localhost`, внутренний домен или частный IP-адрес, либо домен не разрешается в IP-адрес.	Используйте адрес, доступный из интернета. Если ваш сервер еще в разработке, используйте туннель или сервис, который предоставляет публичный HTTPS-URL.
Вебхук с этим URL уже существует	Этот URL использует другой вебхук в аккаунте.	Нажмите Фильтр, введите URL в поле Поиск и нажмите Применить. Затем нажмите три точки на найденном вебхуке, выберите Редактировать и добавьте к нему события.

Когда вы измените URL, нажмите Сохранить, а затем Тестовый запрос, чтобы его проверить.

SendPulse не принимает дополнительный заголовок

Дополнительные заголовки имеют ограничения, а некоторые имена зарезервированы, потому что SendPulse устанавливает их самостоятельно. Сообщения валидации для заголовка следующие:

Сообщение	Причина	Что делать
Этот заголовок зарезервирован и не может быть переопределен	SendPulse устанавливает этот заголовок самостоятельно, например, `Content-Type`, `X-Signature` или `X-Event-Type`.	Используйте другое название заголовка.
Введите действительное название заголовка из 1–128 разрешенных символов	Название пустое, длиннее 128 символов или содержит символы, не разрешенные в именах HTTP-заголовков, такие как пробелы.	Введите название из 1–128 разрешенных символов.
Введите значение заголовка из 1–1024 печатных символов ASCII	Значение пустое, длиннее 1024 символов или содержит символы, отличные от ASCII, такие как нелатинские буквы.	Введите значение из 1–1024 печатных символов ASCII.

Если кнопка Добавить заголовок неактивна, вебхук уже имеет максимум — 10 заголовков. Вместе заголовки вебхука могут занимать до 8 КБ.

Когда вы измените заголовки, нажмите Сохранить, затем нажмите Тестовый запрос и проверьте на своем сервере, что заголовок получен.

Подпись не совпадает с заголовком X-Signature

Ваш сервер вычисляет хеш HMAC-SHA256 от другого тела или с другим ключом. Распространенные причины следующие:

повторно сгенерированный ключ, который не обновили на сервере;
тело, которое разобрали и повторно сериализовали перед проверкой;
сравнение без префикса sha256=;
ключ, использованный как декодированные байты вместо текстовой строки.

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

Вычисляйте хеш от сырого тела запроса, прежде чем парсить JSON.

Сравните результат с целым значением заголовка, включая sha256=, или уберите префикс перед сравнением.

Используйте ключ точно так, как показано в поле, — как текстовую строку.

Нажмите Тестовый запрос и проверьте подпись тестового запроса.

Одно событие приходит несколько раз

Это может произойти по следующим причинам:

автоматический повтор: ваш сервер ответил ошибкой или слишком поздно, поэтому SendPulse отправил тот же запрос снова;
ручной повтор из журнала запросов;
события Тег привязан и Тег отвязан приходят парами: один запрос для подписчика и один для адресной книги. Это не дубликат; поле entity_type в теле запроса различает эти два запроса.

Чтобы это исправить, возвращайте успешный код сразу, прежде чем обрабатывать данные.

Перед обработкой проверяйте, обработал ли ваш сервер это событие. События SMS содержат для этого поле event_id.

Для событий тегов проверяйте поле entity_type.

События приходят не по порядку

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

Чтобы это учесть, упорядочивайте события по полю occurred_at в теле запроса, а не по времени, когда их получил ваш сервер.

Ваш обработчик перестал обрабатывать события после переноса

SendPulse переносит вебхуки сервиса рассылок и SMTP из прежнего раздела API и вебхуки в раздел Вебхуки автоматически и отключает предыдущие записи.

Запросы из перенесенного вебхука также содержат данные в прежнем формате, в элементе "0". Однако перенесенный вебхук отправляет одно событие на запрос вместо массива событий.

Тело запроса — это объект JSON, который содержит элемент "0" и поля user_id, scope, event_type, occurred_at и data. Обработчик, который обрабатывает тело запроса как массив, может завершиться ошибкой на таких запросах.

Чтобы это исправить, перейдите в Настройки аккаунта > Вебхуки, найдите перенесенный вебхук по URL, нажмите три точки на его карточке, выберите Редактировать и проверьте URL и события.

Обновите свой обработчик так, чтобы он читал одно событие из тела запроса вместо итерации по массиву. Чтобы сохранить свой текущий код обработки, читайте событие из элемента "0". Выполните действие, которое вызывает одно из выбранных событий, затем проверьте статус новой записи в журнале запросов.

Не используйте для этой проверки тестовый запрос, потому что он не содержит элемент "0".

В журнале нет старых запросов

SendPulse хранит записи журнала в течение 30 дней, а журнал удаленного вебхука недоступен. Страница показывает 20 записей за раз.

Чтобы просмотреть предыдущие записи за последние 30 дней, нажмите Показать больше. Записи старше 30 дней и журналы удаленных вебхуков восстановить нельзя, поэтому если вам нужна история, храните запросы на своей стороне.

Чтобы приостановить вебхук и сохранить его журнал, нажмите три точки на его карточке и выберите Отключить вместо Удалить.

Участник команды не видит раздел «Вебхуки»

Участник команды видит раздел Вебхуки, только если его роль пользователя имеет право Settings в группе Email and marketing campaigns.

Чтобы это исправить, попросите владельца аккаунта назначить вам кастомную роль пользователя с этим правом. Обновите страницу и перейдите в Настройки аккаунта > Вебхуки.

Подробнее: Как создать кастомную роль пользователя.

Событий чат-ботов и поп-апов нет в списке

Список События в форме вебхука не содержит событий чат-ботов и поп-апов. Вебхуки для чат-ботов и поп-апов настраиваются в параметрах конкретного чат-бота или поп-апа.

Чтобы получать эти события, настройте вебхук для чат-ботов и поп-апов.

Подробнее: Как отправлять вебхуки через чат-ботов, Настройка уведомлений о новых лидах с помощью вебхуков.

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

Чтобы продолжить пользоваться вебхуками, узнайте, как настроить вебхуки, проверить подпись запроса и просмотреть журнал запросов и повторить запросы.