Приём вебхуков: пять обязательных частей
Приём вебхуков на первый взгляд — одна из самых простых задач. Пишете эндпоинт, внешний сервис делает в него POST, вы кладёте данные в базу. Пять строк кода.
Этот код работает — на тестах. В продакшене начинаются вопросы: что будет, если одно и то же событие придёт дважды? Если старое событие, отправленное повторно, придёт после нового? Если кто-то отправит на ваш эндпоинт поддельный запрос?
В этой статье разберём пять частей приёмника вебхуков. Ни одна из них не является необязательной.
1. Проверка подписи
Эндпоинт вебхука — открытая дверь в интернет. Отправить в него запрос может любой, кто знает адрес.
Поэтому серьёзные сервисы добавляют к каждому запросу подпись. Не проверив её, вы рискуете получить поддельное событие «платёж прошёл успешно».
import crypto from 'node:crypto'
function verify(rawBody: Buffer, signature: string, secret: string) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex')
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature),
)
}Здесь две важные детали, и обе часто забывают.
Первая — нужно использовать сырое тело. Если фреймворк распарсил JSON, а вы затем сделали JSON.stringify обратно, изменятся пробелы и порядок полей, и подпись не сойдётся. Поэтому на маршруте вебхука нужно сохранить тело в исходном виде.
Вторая — сравнение за постоянное время. Обычное сравнение через === занимает разное время в зависимости от количества совпавших символов, и это теоретически открывает путь к подбору подписи.
Третье дополнение: если вместе с подписью приходит отметка времени, проверяйте и её. Это защищает от повторной отправки старого запроса — например, отклоняйте события старше пяти минут.
2. Быстрый ответ
Самая частая архитектурная ошибка — выполнять всю работу внутри вебхука.
app.post('/webhooks/payment', async (c) => {
const event = await c.req.json()
await updateOrder(event) // база
await sendReceiptEmail(event) // внешний сервис
await notifyWarehouse(event) // ещё один внешний сервис
return c.text('ok')
})Проблема в том, что отправляющий сервис обычно ждёт ответа лишь несколько секунд. Если почтовый сервис затормозит, вы не успеете ответить, отправитель сочтёт это сбоем и пришлёт событие повторно. Теперь у вас два одинаковых события.
Правильная форма — разделить приём и обработку:
app.post('/webhooks/payment', async (c) => {
const raw = await c.req.arrayBuffer()
if (!verify(Buffer.from(raw), c.req.header('x-signature'), SECRET)) {
return c.text('invalid signature', 401)
}
await db.insert(webhookEvents).values({
provider: 'payment',
eventId: JSON.parse(...).id,
payload: JSON.parse(...),
}).onConflictDoNothing()
return c.text('ok') // сразу
})Приёмник делает всего две вещи: проверяет подпись и сохраняет событие. Остальное выполняет фоновый воркер.
Это разделение даёт ещё одну выгоду: если при обработке возникнет ошибка, событие не потеряется. Оно лежит в базе, и вы сможете запустить его заново.
3. Идемпотентность
Любой отправитель вебхуков рано или поздно пришлёт одно и то же событие дважды. Это не сбой — это их модель гарантий: «доставим хотя бы один раз».
Защита должна стоять в базе, а не в коде:
create table webhook_events (
id uuid primary key default gen_random_uuid(),
provider text not null,
event_id text not null,
payload jsonb not null,
processed_at timestamptz,
received_at timestamptz not null default now(),
unique (provider, event_id)
);unique (provider, event_id) — вся защита в этой строке. Пришедшее повторно событие молча отбрасывается через onConflictDoNothing.
Колонка provider тоже нужна: разные сервисы могут использовать одинаковый формат идентификаторов, и они не должны сталкиваться.
Если отправитель вообще не даёт идентификатор события — редкость, но встречается — соберите его сами: из хеша тела и отметки времени. Это не идеально, но ловит большинство повторов.
4. События не по порядку
Это самая часто упускаемая проблема.
Вебхуки могут приходить не в том порядке, в котором произошли. Событие «заказ оплачен» может прийти раньше «заказ создан» — например, если первое было отправлено повторно.
Простое решение: в каждом событии есть версия или отметка времени, и вы не применяете более старое.
await db.update(orders)
.set({ status: event.status, statusUpdatedAt: event.occurredAt })
.where(and(
eq(orders.id, event.orderId),
lt(orders.statusUpdatedAt, event.occurredAt), // только если новее
))Если условие не выполняется, обновления не происходит, и старое событие тихо игнорируется. Ровно то поведение, которое нужно.
Если порядок критичен, есть второй путь: сохранить событие и не обрабатывать, пока не придёт ожидаемое предыдущее. Но это сложнее и в большинстве случаев избыточно — сравнения версий обычно достаточно.
5. Наблюдаемость
Вебхук — невидимый поток. О его поломке вам никто не сообщит; вы узнаете об этом, только когда пожалуется клиент.
Я слежу за тремя вещами:
- Количество необработанных событий — где
processed_at is nullи возраст больше пяти минут. Должно быть нулём. - Количество ошибок подписи — должно быть нулём. Если не ноль, то либо неверный секрет, либо кто-то вас прощупывает.
- Возраст последнего события — если обычно приходят десятки событий в час, а последние три часа тишина, скорее всего, проблема на стороне отправителя.
Третий пункт особенно полезен, потому что он ловит отсутствие событий — а это упускают из виду чаще, чем ошибки.
Кроме того, заведите привычку сохранять сырое тело. Место на диске дёшево, а при разборе проблемы ответ на вопрос «что именно пришло?» бесценен.
Итог
Надёжный приёмник вебхуков работает так:
- Берёт сырое тело и проверяет подпись за постоянное время.
- Сохраняет событие с ограничением
unique (provider, event_id). - Немедленно возвращает
200. - Фоновый воркер обрабатывает и отбрасывает устаревшие события по версии.
- Три числа под наблюдением.
В этом списке нет сложных технологий — хватит одной таблицы и одного фонового воркера. Но если хотя бы одна из пяти частей отсутствует, проблема обязательно проявится. И худшее в проблемах с вебхуками то, что они происходят молча: ничего не падает, просто данные становятся неверными.