Сценарий

Обработка вебхуков: проверка подписи, быстрый ответ и вынесение долгой работы

Партнёр обычно ждёт короткий HTTP-ответ. Проверяете подпись: неверная — сразу отказ, верная — быстрый успех. Долгую работу не оставляете в этом запросе — переносите в пайплайн или фоновую задачу. Если партнёр отправит то же событие снова, повторный запрос с тем же id события не должен второй раз менять ваши данные.

Создать маршрут вебхука →Вход вебхуков

Нагрузка и где ломается

Режимы отказа

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

Перегруженная общая точка входа тянет вниз пользовательский трафик.

One overloaded endpoint drags down unrelated user traffic.

Где костыли не спасают

Частые ярлыки

Пропуск проверки подписи «временно».

Синхронные записи в БД до 200 OK.

Как помогает Inquir

Структура

Отдельные функции на провайдера снижают случайное связывание.

Пайплайны продолжают работу после быстрого HTTP-ответа.

Что получаете

Инструменты

Доступ на уровне маршрута

Ключи API или свои схемы на API-Gateway.

Трассы

Видно, на каком шаге сбой — проверка, постановка в очередь или запись.

Маршрутизация тенантов

Хосты или префиксы под отдельные URL вебхуков.

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

Как обрабатывать вебхуки на Inquir Compute

Проверка подписи, быстрый ответ провайдеру, идемпотентные записи.

Проверить событие

Ранний отказ при неверной подписи.

Ответить

Ответьте быстро в лимитах провайдера.

Обработать

Идемпотентные записи по идентификатору события у провайдера.

Пример кода

Ключ идемпотентности

Тело строкой; после проверки подписи разберите JSON. Зафиксируйте идентификатор провайдера до изменения состояния.

persist.mjs

// provider -> gateway route -> fast 200 -> job/pipeline -> apply
export async function handler(event) {
  const evt = JSON.parse(event.body || '{}');
  if (await alreadyHandled(evt.id)) {
    return { statusCode: 200, body: 'duplicate' };
  }
  await handle(evt);
  return { statusCode: 200, body: 'ok' };
}

Когда подходит

Когда это уместно

Интеграции SaaS
Платежи
События с Git-хостинга

Когда лучше не трогать

Двунаправленные сокеты — другой класс транспорта

FAQ

Вопросы и ответы

Зачем не трогать сырое тело для HMAC?

Провайдеры подписывают точные байты; пересборка JSON ломает подпись.

Тяжёлая работа до 200?

Нет — подтверждение в лимите провайдера, продолжение в пайплайне или фоновой задаче, чтобы повторы не дублировали дорогие эффекты.

Дубликаты доставки?

ID события провайдера как ключ идемпотентности: «видели» до мутации данных.