Чек-лист вебхуков Node.js для повторных попыток и проверки подписи

Почему обработка вебхуков ломается так легко

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

Такое поведение с повторами нормально. Сервис платежей или биллинга не может считать, что ваше приложение обработало событие, только потому что отправил его один раз. Если ваш сервер ловит тайм-аут через 10 секунд или возвращает ошибку 500 из-за краткого сбоя базы данных, провайдер обычно пробует ещё раз. Иногда это происходит через несколько минут. Иногда — несколько раз подряд.

Именно так и начинается двойная работа. Если ваш обработчик каждый раз создаёт счёт, отправляет квитанцию или помечает заказ как оплаченный при каждом появлении одного и того же события, один клиент может заплатить дважды или получить три копии одного письма. Ошибка часто маленькая: код спрашивает не «получил ли я вебхук?», а «обработал ли я уже этот ID события?»

Проверка подписи добавляет ещё одну острую грань. Многие провайдеры подписывают сырое тело запроса, а не распарсенный JSON-объект. Если Express или другой middleware изменит тело до проверки, даже безобидно, подпись не сойдётся. Лишний пробел, переставленные поля или автоматический парсинг могут всё сломать. Команды часто тратят на это часы, потому что payload в логах выглядит правильным, но сырые байты уже не совпадают с тем, что подписал провайдер.

Слабые журналы доставки делают отладку ещё тяжелее. Когда начинается инцидент, нужно быстро ответить на базовые вопросы: какое событие пришло, сколько раз, какие заголовки были в запросе, что ответило ваше приложение и завершился ли обработчик или упал на полпути. Если логи говорят только «webhook failed», вы не поймёте, в чём проблема: в плохой подписи, тайм-ауте или повторной обработке.

Хороший чек-лист вебхуков Node.js начинается с этой реальности: повторы ожидаемы, дубликаты нормальны, а расплывчатые логи превращают маленькую ошибку в длинную ночь.

Что включает безопасная настройка вебхуков

Точка приёма вебхука должна делать пять вещей в правильном порядке. Если нарушить этот порядок, мелкие ошибки превращаются в двойные списания, пропущенные обновления или обращения в поддержку, на разбор которых уходят часы. Хороший чек-лист вебхуков Node.js начинается ещё до бизнес-логики и заканчивается журналами, которым можно доверять.

Сначала сохраните сырое тело запроса ровно в том виде, в каком оно пришло. Многие провайдеры подписывают сырые байты, а не распарсенный JSON-объект. Если ваше приложение на Express или Fastify разбирает тело слишком рано, проверка подписи может провалиться, даже если отправитель настоящий.

Потом проверьте подпись, прежде чем доверять чему-либо в payload. Сверьте общий секрет, а если провайдер отправляет timestamp, проверьте и его. Старые подписанные запросы не должны проходить бесконечно.

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

Безопасный поток обычно выглядит так:

• Прочитать сырое тело и заголовки.
• Проверить подпись и быстро отклонить плохие запросы.
• Сохранить ID события или хэш со статусом получения.
• Отправить медленную работу в очередь.
• Быстро вернуть успешный ответ и залогировать результат.

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

Логи замыкают цикл. Храните по одной записи на каждую попытку доставки: ID события, имя провайдера, время получения, код ответа, состояние обработки и сообщение об ошибке, если что-то пошло не так. Во время инцидента эта история показывает, повторял ли отправитель попытки, приняло ли приложение событие и завершил ли воркер работу или остановился на полпути.

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

Какие Node.js-пакеты стоит проверить

Чтобы сделать вебхуки безопасными, не нужен огромный стек. В большинстве Node.js-приложений хватит пяти инструментов: одного web-фреймворка, который сохраняет сырое тело запроса, одного способа проверять подписи, одной очереди для повторов, одного логгера и одного хранилища для дедупликации.

Express и Fastify оба подходят, но только если вы сохраните сырое тело до того, как JSON-парсинг его изменит. Проверка подписи часто падает из-за того, что parser переформатировал payload. В Express команды обычно сохраняют сырой буфер через middleware или используют raw parser для маршрута вебхука. В Fastify для этого подходит поддержка raw body или плагин.

Для проверки подписи начните с node:crypto, если провайдер ясно описал алгоритм. Так код остаётся компактным, и вам не нужен лишний пакет. Если у провайдера есть SDK-хелпер для подписанных вебхуков, используйте его. Такие хелперы обычно лучше обрабатывают timestamp и сравнение в постоянное время, чем самописный код.

Очередь помогает, если ваш обработчик делает больше, чем быструю проверку и одну запись в базу. BullMQ — хороший выбор, если у вас уже есть Redis и нужны задержки повторов, backoff и видимость задач. Bee-Queue легче и проще держится в голове, хотя даёт меньше дополнительных возможностей.

Структурированные логи экономят реальное время во время инцидентов. Pino быстрый и простой. Winston тоже подходит, особенно если приложение уже использует его. Логируйте провайдера, ID события, ID доставки, результат проверки подписи, номер попытки, итог обработки и время выполнения.

Для дедупликации и блокировок используйте то хранилище, которому вы уже доверяете в продакшне:

• Используйте pg, если нужны надёжные записи об идемпотентности с уникальными ограничениями.
• Используйте ioredis для быстрых проверок дублей и краткоживущих блокировок.
• Используйте оба, если Postgres хранит истину, а Redis обрабатывает всплески повторов.

Этого достаточно для практичного чек-листа вебхуков Node.js. Решение остаётся небольшим и закрывает те сбои, которые чаще всего приводят к двойной работе и пропущенным событиям.

Как выстроить поток шаг за шагом

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

Начните с HTTP-края. В Node.js прочитайте сырое тело запроса до того, как его изменит JSON-парсинг. Многие схемы подписи зависят от точного набора байтов, поэтому даже безобидные изменения форматирования могут сломать проверку. Сохраните и заголовки, особенно timestamp, подпись и любую метаинформацию о событии, которую отправитель добавляет в запрос.

Далее проверьте свежесть и подлинность. Сравните timestamp с коротким допустимым окном, а затем вычислите ожидаемую подпись из сырого тела и общего секрета. Если хотя бы одна проверка не проходит, остановитесь и запишите попытку в журнал доставки с понятным статусом, например «неверная подпись» или «истёк timestamp».

После этого достаньте поля, которые нужны для отслеживания события: стабильный ID события, тип события и систему-источник. Эти три поля важнее, чем думают многие команды. Они помогают понять, является ли запрос повторной попыткой, какой обработчик должен сработать и откуда пришло событие, если у двух провайдеров похожие названия.

Прежде чем трогать бизнес-данные, запишите запись для дедупликации по ключу из ID события и источника. Делайте это сначала, а не после обработки. Если два одинаковых запроса придут с разницей в секунду, второй должен наткнуться на эту запись и остановиться. Это одна из самых полезных частей любого чек-листа вебхуков Node.js, потому что она предотвращает двойную работу даже тогда, когда повторы накапливаются.

Затем отправьте реальную работу в очередь и быстро верните ответ 2xx. Отправители вебхуков обычно повторяют попытку, если endpoint слишком долго остаётся открытым. Очередь укорачивает путь запроса и даёт запас для безопасных повторных попыток на стороне downstream.

Когда воркер забирает задачу, обрабатывайте её через идемпотентные обработчики. Например, если заказ уже помечен как оплаченный, не ставьте этот статус ещё раз и не отправляйте второе письмо. Обновляйте журнал доставки по мере того, как задача проходит путь от полученной к поставленной в очередь, обработанной или завершившейся ошибкой. В плохой день именно этот журнал позволяет быстро ответить на один простой вопрос: что случилось с этим событием?

Журналы доставки, которые помогают во время инцидентов

Когда вебхук падает в 2 часа ночи, обычные логи приложения редко отвечают на первый вопрос: «Что случилось с этим событием?» Нужен журнал доставки, в котором каждый вебхук — это отслеживаемая запись, а не россыпь разрозненных строк.

Начните с идентификатора. Сохраните ID события провайдера при получении, а потом добавьте свой внутренний ID задачи, когда приложение поставит работу в очередь или начнёт её выполнять. Эта пара быстро снимает массу путаницы. ID от провайдера показывает, что, по его мнению, он доставил. Ваш ID задачи показывает команде, что именно сделала с этим ваша система.

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

Держите результат на виду. Для каждой попытки записывайте код HTTP-ответа, короткое сообщение об ошибке и время обработки в миллисекундах. Если обработчик начинает ловить тайм-ауты после 8 секунд, вы хотите видеть этот паттерн на одном экране. Если проверка подписи не проходит, текст ошибки должен говорить об этом прямо, а не прятаться за общим «плохим запросом».

Командам поддержки нужен не только сырой массив данных, но и быстрый поиск. Дайте им возможность искать журналы доставки по ID клиента, ID заказа и ID события. Клиент обычно начинает с фразы «платёж прошёл, но ничего не обновилось». Поддержка должна находить связанные доставки за секунды, не прося инженера копаться в логах вручную.

Метки статуса делают журнал понятнее под давлением. Ясно помечайте события как received, processed, duplicate, ignored, failed или replayed. Такие метки не дают людям гадать. Дубликат и повторный запуск могут выглядеть похоже в трафике, но во время расследования это разные вещи.

Небольшой пример делает всё нагляднее. Если вебхук order.paid приходит три раза, в журнале должна быть одна запись с ID события провайдера, одним ID заказа, первым появлением в 10:02:14, последней попыткой в 10:06:41, счётчиком повторов 2, одним успешным ID задачи, а последующие попытки должны быть помечены как duplicate. Именно такая запись завершает инцидент быстрее, чем любой график в дашборде.

Повторный запуск без повторного ущерба

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

Повторный запуск не должен идти по укороченному пути. Используйте тот же сырой payload, те же заголовки и ту же метаинформацию о событии, что были в исходном запросе, а затем снова прогоняйте те же проверки подписи и источника. Если в системе не сохранено достаточно данных для этих проверок, не гадайте. Откажитесь от повторного запуска и пометьте событие как не подлежащее повтору.

Оставьте один путь выполнения

Самая безопасная схема простая: живой вебхук и ручной повторный запуск вызывают один и тот же обработчик. Этот обработчик сначала проверяет, изменило ли событие состояние раньше, и только потом делает что-либо ещё. Если платёж уже пометил счёт как оплаченный, повторный запуск должен записать «already applied» и остановиться. Он не должен отправлять ещё одну квитанцию, создавать ещё одну запись в книге или дважды уведомлять склад.

Именно здесь идемпотентные обработчики и окупаются. Они делают повторный запуск скучным, а это именно то, что вам нужно.

Каждый раз, когда кто-то повторно запускает событие, сохраняйте короткий след аудита:

• кто инициировал повторный запуск
• зачем это сделали
• когда его выполнили
• какое событие повторили
• каким был результат

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

Задайте срок действия

Старые события могут принести больше вреда, чем пользы. Повторный запуск через полгода может ссылаться на удалённые записи, старые бизнес-правила или схему, которую вы больше не поддерживаете. Задайте понятный cutoff и соблюдайте его. Многие команды используют короткое окно — например, 7, 14 или 30 дней, а после этого требуют ручного исправления данных.

Если вы добавите только одну вещь из чек-листа вебхуков Node.js, пусть это будет она: повторный запуск полезен только тогда, когда он проверен, залогирован и безопасен для повторного выполнения.

Простой пример вебхука для оплаты заказа

Провайдер платежей отправляет order.paid в ваше Node.js-приложение. Первая доставка доходит до сервера, но провайдер ловит тайм-аут, прежде чем увидит ваш ответ. Через несколько секунд он пробует ещё раз, поэтому приложение получает одно и то же событие дважды.

Первая проверка — это подпись, и она должна использовать сырое тело запроса. Если сначала распарсить JSON, даже небольшое изменение пробелов или порядка полей может сломать проверку хэша. На практике маршрут читает сырой payload, сравнивает подпись провайдера с вашим результатом HMAC и быстро отклоняет запрос, если они не совпадают.

После этого обработчик сохраняет ID события провайдера в таблицу дедупликации с уникальным ограничением. Представьте себе строки вроде evt_10492, тип события, ID заказа, время получения и статус. Если вставка проходит, событие новое, и приложение может отправить работу в очередь. Если база говорит, что такой ID уже существует, вы останавливаетесь и возвращаете успех, чтобы провайдер не продолжал повторять попытки.

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

Простой поток выглядит так:

• проверить подпись на сыром payload
• вставить ID события в таблицу дедупликации
• поставить задачу на обработку заказа в очередь
• один раз пометить заказ как оплаченный и отправить одну квитанцию

Журнал доставки должен делать результат очевидным во время инцидента:

10:02:14 received order.paid evt_10492 for order_781
10:02:14 signature ok
10:02:14 dedupe insert ok
10:02:15 worker marked order_781 as paid
10:02:16 receipt sent
10:02:21 received order.paid evt_10492 for order_781
10:02:21 signature ok
10:02:21 duplicate event, skipped

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

Ошибки, из-за которых появляется двойная работа или теряются события

Большая часть двойной работы начинается с одного неверного предположения: ответ 200 значит, что событие в безопасности. Это не так. Если процесс падает до того, как вы сохраните событие, отправитель считает доставку успешной, а ваше приложение забывает, что вообще что-то произошло.

Безопасный шаблон намеренно скучный:

• сначала прочитать сырое тело
• проверить подпись на этих точных байтах
• сохранить ID события и детали запроса в общем хранилище
• вернуть 200 только после успешной записи
• выполнять медленную работу в фоновом задании

Сырой body часто подводит команды на Node.js. Проверка подписи обычно использует точные байты запроса. Если middleware сначала парсит JSON, оно может изменить пробелы, порядок полей или кодировку. Проверка падает, или, что ещё хуже, вы перестаёте её делать, потому что она кажется нестабильной. В Express это обычно означает, что вы сохраняете сырые данные до того, как их коснётся express.json().

Ещё одна частая ошибка — выполнять побочные эффекты внутри обработчика запроса. Если этот обработчик отправляет письмо, пишет в несколько таблиц или вызывает другой API, тайм-аут может оставить вас в незавершённом состоянии. Провайдер повторяет попытку. И вот клиент получает два письма или один и тот же заказ уходит дважды.

Хранение записей дедупликации только в памяти ломается в тот момент, когда вы перезапускаете приложение или запускаете больше одного экземпляра. Один сервер помнит событие. Другой — нет. Храните данные дедупликации в базе данных или Redis и, где возможно, ставьте уникальное ограничение на ID события.

Логирование тоже может сделать плохой день ещё хуже. Если ваши логи говорят только «signature failed» или «job error», вы потеряете час, гадая, какой именно запрос сломался. Логируйте ID события провайдера, ваш request ID, время попытки и итог обработчика. Эта маленькая привычка сильно упрощает журналы доставки и повторный запуск.

Если вам нужен простой тест для чек-листа вебхуков Node.js, остановите приложение сразу после получения события, отправьте то же событие три раза и посмотрите, что произойдёт. Хорошие обработчики остаются спокойными. Они сохраняют один раз, обрабатывают один раз и точно объясняют, что пошло не так.

Короткая проверка перед запуском

Чек-лист вебхуков Node.js имеет смысл только тогда, когда вы проверяете грязные случаи, а не просто первый успешный запрос. Прогоните эти проверки в staging с настоящими подписями, настоящими правилами повторов и тем же набором очереди и воркеров, который планируете использовать в продакшне.

Перед релизом докажите пять вещей:

• Вы можете повторно запустить одно неудачное событие из журналов доставки и увидеть, как оно завершается без проблем. Если для повторного запуска сначала нужен ручной фикс в базе, поток всё ещё хрупкий.
• Две копии одного события оставляют систему в том же состоянии, что и одна копия. Один заказ должен остаться одним заказом, один возврат — одним возвратом, одно письмо — одним письмом.
• Вы можете отследить одно событие от получения до результата воркера. Начните с ID события провайдера, а потом проследите его через валидацию, постановку в очередь, обработку и финальный статус.
• Повторы останавливаются после фиксированного лимита. После этого событие должно перейти в очередь на проверку или dead letter queue, а не продолжать падать бесконечно.
• Оповещения срабатывают, когда число ошибок начинает расти. Спровоцируйте несколько плохих доставок подряд и проверьте, что кто-то из команды действительно получил предупреждение.

Короткий прогон ловит многое. Отправьте событие order.paid с валидной подписью. Отправьте то же событие ещё раз. Затем отправьте одно с повреждённым payload или плохой подписью. В логах должно быть видно, что первое событие прошло успешно, дубликат был проигнорирован без ущерба, а плохой запрос провалился по понятной причине.

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

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

Что делать дальше

Начните с малого. Возьмите один вебхук, например order_paid, и нарисуйте весь его путь на бумаге: получить запрос, проверить подпись, сохранить сырое тело, проверить ID события, отправить работу в очередь, выполнить обработчик и записать результат. Большинство команд пропускают этот шаг, а потом вслепую отлаживают систему, когда повторы начинают наслаиваться друг на друга.

Сделайте три ранних решения и оставьте их скучными: одна очередь, один формат логов и одно хранилище для дедупликации. Слишком раннее смешивание инструментов усложняет чтение инцидентов. Простая запись в Redis или таблица в Postgres для обработанных ID событий часто работает лучше, чем хитрая схема, которой никто не доверяет под давлением.

Чек-лист вебхуков Node.js помогает только тогда, когда вы тестируете неприятные случаи, а не только счастливый путь. Ломайте поток специально и смотрите, где он гнётся.

• Отправьте запрос с плохой подписью и убедитесь, что приложение быстро его отклоняет.
• Вызовите тайм-аут и проверьте, что повторные попытки вебхука не создают двойную работу.
• Повторно отправьте один и тот же ID события несколько раз и убедитесь, что обработчик выходит, не делая работу снова.
• Прочитайте журналы доставки и спросите себя, смог бы другой разработчик объяснить сбой за пять минут.

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

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

Если вашей команде нужен серьёзный разбор, Oleg Sotnikov может помочь выстроить потоки вебхуков, очереди повторов и идемпотентные обработчики в роли Fractional CTO. Такой разбор может выявить недостающий защитный барьер, из-за которого одна повторная попытка превращается в баг для клиента.