Как принимать вебхуки и обрабатывать повторы
На этой странице
Вебхук — HTTP-уведомление от другого сервиса. Подпись подтверждает отправителя, а идемпотентность позволяет безопасно принять одно событие несколько раз.
Вопрос
Как отличить настоящее уведомление от подделки и не повторить изменение при повторной доставке?
Основная идея
Cookie пользователя здесь не нужна: запрос приходит от сервиса. Провайдер задает собственный протокол подписи. Для Stripe и других платформ используй их SDK; следующий пример показывает учебный собственный протокол, несовместимый с их подписями.
Контракт: x-demo-timestamp содержит Unix-время в секундах, x-demo-signature — hex HMAC-SHA256 от строки timestamp.rawBody. Общий WEBHOOK_SECRET известен двум серверам.
Пример: журнал событий с защитой от повторов
Дополнительная миграция для PostgreSQL:
-- migrations/002_webhook_events.sql
CREATE TABLE webhook_events (
event_id text PRIMARY KEY,
event_type text NOT NULL,
received_at timestamptz NOT NULL DEFAULT now()
);// app/api/webhooks/demo/route.ts
import { createHmac, timingSafeEqual } from "node:crypto";
import { z } from "zod";
import { pool } from "@/lib/db";
import { AppError } from "@/lib/errors";
import { apiError } from "@/lib/http";
export const runtime = "nodejs";
export async function POST(request: Request) {
try {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) throw new Error("Не настроен WEBHOOK_SECRET");
const timestamp = request.headers.get("x-demo-timestamp") ?? "";
const signature = request.headers.get("x-demo-signature") ?? "";
if (!/^\d{10}$/.test(timestamp) || !/^[a-f0-9]{64}$/.test(signature)) {
throw new AppError(400, "Неверная подпись");
}
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
throw new AppError(400, "Истек срок уведомления");
}
const raw = await request.text();
const expected = createHmac("sha256", secret)
.update(`${timestamp}.${raw}`).digest();
if (!timingSafeEqual(expected, Buffer.from(signature, "hex"))) {
throw new AppError(400, "Неверная подпись");
}
const event = z.object({
id: z.string().min(1).max(100),
type: z.literal("demo.created"),
}).parse(JSON.parse(raw));
const result = await pool.query(
`INSERT INTO webhook_events(event_id, event_type) VALUES ($1, $2)
ON CONFLICT (event_id) DO NOTHING RETURNING event_id`,
[event.id, event.type],
);
return Response.json({ received: true, duplicate: result.rowCount === 0 });
} catch (error) { return apiError(error); }
}Событие {"id":"evt_1","type":"demo.created"} запишется один раз. Повторная доставка вернет успешный ответ с duplicate: true. База атомарно обеспечивает уникальность, в том числе при конкурентных запросах.
Что важно помнить
Подпись проверяют по исходному телу до его преобразования. Время ограничивает повторное использование старого запроса, идентификатор события предотвращает повторную обработку.
Пример только записывает журнал. Если событие меняет заказ, запись события и изменение заказа должны выполняться в одной транзакции либо через надежный inbox/очередь. Иначе можно отметить событие полученным и потерять работу после сбоя.
Провайдеры повторяют доставку и могут менять порядок событий. Ограничивай размер тела, быстро подтверждай надежно сохраненное событие и выноси долгую работу в очередь.
Мини-шпаргалка
- Проверяй подпись согласно конкретному провайдеру.
- Используй raw body, а не повторно собранный JSON.
- Повтор события не должен повторять эффект.
- Для долгой обработки нужна надежная очередь.