Як усунути проблеми з вебхуками

Зазвичай подія стається, 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-адресу вебхука, подію й дату та час запиту з журналу.

Щоб продовжити користуватися вебхуками, дізнайтеся, як налаштувати вебхуки, перевірити підпис запиту та переглянути журнал запитів і повторити запити.