Ідемпотентний вебхук у n8n, який пропускає повторні запити
Зберігайте ключі ідемпотентності в data table n8n, пропускайте послідовні повтори, тестуйте в Executions і враховуйте обмеження паралельності.
Перевірено за документацією n8n .
Що означає ідемпотентність для вебхука і що вам знадобиться
Просте визначення нашими словами: вебхук ідемпотентний, коли повторне отримання того самого запиту не створює другого запису й не повторює побічну дію. Це важливо, бо багато відправників надсилають запит повторно, якщо не отримали чіткої відповіді. Як і коли вони це роблять, залежить від відправника, і документація n8n, використана для цього посібника, цього не описує.
Перед початком вам потрібні три речі. По-перше, власний інстанс n8n. По-друге, workflow, що починається з тригера Webhook. По-третє, доступ до data tables. Також потрібен відправник, який додає до кожного запиту власний ключ ідемпотентності, наприклад у заголовку або полі тіла. Радимо не генерувати ключ усередині n8n. Ключ, створений для кожного виконання, щоразу інший, тож він не покаже, що два запити насправді однакові.
Мета — один запис на ключ ідемпотентності, навіть коли відправник повторює запит. Нові ключі запускають побічну дію, як-от створення замовлення чи надсилання листа. Повторні ключі отримують зрозумілу відповідь, і більше нічого не відбувається. Цей посібник базується на офіційній документації. Ми не перевіряли його власноруч.
Кроки 1 і 2: захистіть вебхук і створіть таблицю ключів
Додайте вузол Webhook. У налаштуваннях автентифікації вимагайте від викликачів Basic, Header або JWT auth. Логіка проста: так ви обмежуєте, хто може викликати вебхук. Налаштування облікових даних описано на окремій сторінці документації. Далі встановіть опцію Respond на використання вузла Respond to Webhook. Це дає змогу вибрати, що отримає відправник, зокрема власний код відповіді. Пам’ятайте, що вузол Respond to Webhook виконується лише один раз і використовує перший вхідний елемент.
Також пам’ятайте, що production URL стає активним лише після публікації workflow.
Тепер створіть data table для оброблених ключів. Проста структура — стовпець для ключа і, за бажанням, стовпець із часом отримання. Документація n8n прямо згадує зберігання позначок для запобігання дублікатам запусків як сценарій використання data tables, тож це відповідає їхньому призначенню.
Кроки 3–5: перевірка, запис, дія і відповідь
Крок 3: одразу після вебхука додайте вузол Data Table, який розділяє вхідні елементи залежно від того, чи вже існує відповідний рядок. Порівнюйте ключ із запиту зі стовпцем ключів. Тепер у вас дві гілки: нові ключі та ключі, які ви вже бачили.
Крок 4: у гілці нових ключів вставте ключ операцією Insert, а потім виконайте побічну дію. Тут є компроміс, який варто обрати свідомо. Якщо записати ключ спочатку, збій під час побічної дії призведе до того, що повтор буде пропущено, і робота може так і не виконатися. Якщо записати ключ після побічної дії, збій між ними може дозволити повтору виконати її ще раз. Доступна також операція Upsert, яка оновлює вже наявний рядок. Проте документація не стверджує, що вона безпечна, коли запити надходять одночасно.
Крок 5: завершіть обидві гілки вузлом Respond to Webhook. Як редакційна порада: для дублікатів теж повертайте статус успіху з повідомленням, що запит уже оброблено. Тоді відправники не матимуть причин повторювати спроби. n8n не вимагає конкретного коду статусу. Вибір за вами та вашим відправником.
Крок 6: протестуйте, надіславши той самий запит двічі
Опублікуйте workflow і надішліть один запит із вигаданим ключем через будь-який HTTP-клієнт. Потім надішліть точно такий самий запит ще раз. Очікуваний результат: перший виклик виконує побічну дію й додає один рядок, а другий отримує вашу відповідь для дубліката без додавання рядка. Надішліть третій запит з іншим ключем, щоб переконатися, що нові ключі й далі проходять.
Дані production-запусків не відображаються в редакторі, тож відкрийте вкладку Executions workflow, щоб побачити, якою гілкою пройшов кожен запуск. Потім перевірте data table і переконайтеся, що для повторного ключа є лише один рядок.
Sources: S1
Альтернатива: вузол Remove Duplicates
Якщо вам не потрібна таблиця, яку можна переглядати, вузол Remove Duplicates може відкидати елементи, значення яких траплялися в попередніх виконаннях. Він доступний у n8n 1.64.0 і новіших версіях. За замовчуванням він зберігає 10 000 елементів, і цей розмір можна змінити. Дуже старі ключі з часом можуть випасти з цієї історії. Документація не пояснює, що відбувається з найстарішими записами, тож не покладайтеся на нього для ключів, які треба пам’ятати довго. Його поведінку при одночасних запитах також не задокументовано.
Sources: S5
Усунення проблем і відоме обмеження паралельності
Відправник отримує помилку 500: якщо workflow падає до виконання вузла Respond to Webhook, n8n повертає 500. Деякі відправники після цього повторюють запит, тож помилка тут може створити саме ті повтори, які ви намагаєтеся обробити. Відкрийте Executions, щоб знайти вузол, що завершився з помилкою.
Вставки раптово не працюють: data tables призначені для легкого чи помірного зберігання. За замовчуванням усі таблиці в інстансі мають спільний ліміт 200 MiB. Коли його досягнуто, вставки не виконуються, а виконання завершуються з помилкою. У self-hosted інстансах ліміт можна підвищити через N8N_DATA_TABLES_MAX_SIZE_BYTES.
У production нічого не відбувається: перевірте, чи опубліковано workflow.
Відоме обмеження: використана тут документація не гарантує, що перевірка і вставка відбуваються як один атомарний крок, і не згадує унікальні обмеження. Два однакові запити, що надійшли одночасно, можуть обидва пройти перевірку й обидва виконати побічну дію. Ця схема розрахована на повтори, що надходять один за одним, але ми не тестували її власноруч, і вона не гарантує захисту від одночасних запитів. Для платежів чи інших критичних побічних дій покладайтеся на систему, яка забезпечує унікальне обмеження на рівні бази даних.
