Webhook-система с логированием и повторной отправкой: настройка под ключ

Вы запустили интеграцию с CRM-партнёра. Первые события уходят, но через час клиент жалуется, что не получил половину уведомлений. Логи молчат — получатель отвечал 200, но данные не обработал. Без детализации каждой попытки выяснить причину — гадание. Мы разрабатываем Webhook-системы с полным логированием и повторной отправкой: не просто «послать и забыть», а контроль каждого события. 5+ лет в интеграциях B2B, 100+ проектов — гарантируем прозрачность и надёжность.

Webhook — это исходящий HTTP-запрос, который вы не контролируете до конца. Получатель может вернуть 200, не обработав данные. Может упасть через 9 секунд после получения. Может пропустить событие без следа. Без детального логирования всех попыток и возможности ручной повторной отправки отладить проблемы с интеграцией практически невозможно.

Почему логирование каждой попытки — основа надёжной webhook-системы?

Допустим, событие упало на третьей попытке после таймаута. Если не хранить историю, вы увидите только финальный статус. А так — полная картина: первая попытка упала с 500, вторая с таймаутом через 8 секунд, третья — 502. Это сразу указывает на проблемы на стороне получателя. Системы без логирования попыток заставляют разработчиков тратить часы на воспроизведение. Наш подход сокращает время отладки в среднем в 5 раз по сравнению с традиционным мониторингом.

Какие данные мы логируем и как это реализовано?

Минимальный набор данных на каждую попытку доставки:

Храним попытки отдельно от доставок — одна доставка может иметь 8 попыток. Это позволяет видеть полную историю и понимать, на каком шаге всё пошло не так.

CREATE TABLE webhook_attempts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  delivery_id UUID NOT NULL REFERENCES webhook_deliveries(id) ON DELETE CASCADE,
  attempt_number INTEGER NOT NULL,
  started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  duration_ms INTEGER,
  request_body JSONB,
  request_headers JSONB,
  response_code INTEGER,
  response_headers JSONB,
  response_body TEXT,           -- обрезается до 2000 символов
  error_message TEXT,
  success BOOLEAN NOT NULL DEFAULT false
);

CREATE INDEX idx_attempts_delivery ON webhook_attempts(delivery_id);
CREATE INDEX idx_attempts_started ON webhook_attempts(started_at DESC);

Реализация логирования:

class WebhookAttemptLogger
{
    public function log(
        WebhookDelivery $delivery,
        int $attempt,
        WebhookAttemptData $data
    ): WebhookAttempt {
        return WebhookAttempt::create([
            'delivery_id'      => $delivery->id,
            'attempt_number'   => $attempt,
            'started_at'       => $data->startedAt,
            'duration_ms'      => $data->durationMs,
            'request_body'     => $delivery->payload,
            'request_headers'  => $data->requestHeaders,
            'response_code'    => $data->responseCode,
            'response_headers' => $data->responseHeaders,
            'response_body'    => $data->responseBody
                ? mb_substr($data->responseBody, 0, 2000)
                : null,
            'error_message'    => $data->errorMessage,
            'success'          => $data->success,
        ]);
    }
}

class SendWebhookJob implements ShouldQueue
{
    public function handle(
        WebhookAttemptLogger $logger
    ): void {
        $startedAt = now();
        $requestHeaders = $this->buildHeaders();

        try {
            $response = Http::timeout(15)
                ->withHeaders($requestHeaders)
                ->post($this->delivery->subscription->endpoint_url, $this->delivery->payload);

            $durationMs = (int)(microtime(true) * 1000 - $startedAt->timestamp * 1000);

            $logger->log($this->delivery, $this->delivery->attempt_count, new WebhookAttemptData(
                startedAt: $startedAt,
                durationMs: $durationMs,
                requestHeaders: $requestHeaders,
                responseCode: $response->status(),
                responseHeaders: $response->headers(),
                responseBody: $response->body(),
                success: $response->successful(),
            ));

            if ($response->successful()) {
                $this->delivery->markDelivered();
            } else {
                $this->delivery->scheduleRetry();
            }

        } catch (\Throwable $e) {
            $durationMs = (int)(microtime(true) * 1000 - $startedAt->timestamp * 1000);

            $logger->log($this->delivery, $this->delivery->attempt_count, new WebhookAttemptData(
                startedAt: $startedAt,
                durationMs: $durationMs,
                requestHeaders: $requestHeaders,
                errorMessage: get_class($e) . ': ' . $e->getMessage(),
                success: false,
            ));

            $this->delivery->scheduleRetry();
        }
    }
}

Как организована ручная повторная отправка?

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

class WebhookDeliveryController extends Controller
{
    // Повторить конкретную доставку
    public function resend(WebhookDelivery $delivery): JsonResponse
    {
        abort_if(
            $delivery->status === 'delivered',
            422,
            'Delivery already succeeded'
        );

        $delivery->update([
            'status'          => 'pending',
            'attempt_count'   => 0,
            'next_attempt_at' => now(),
        ]);

        SendWebhookJob::dispatch($delivery);

        return response()->json(['queued' => true]);
    }

    // Повторить все упавшие доставки подписки
    public function resendFailed(WebhookSubscription $subscription): JsonResponse
    {
        $count = WebhookDelivery::where('subscription_id', $subscription->id)
            ->where('status', 'failed')
            ->count();

        WebhookDelivery::where('subscription_id', $subscription->id)
            ->where('status', 'failed')
            ->update([
                'status'          => 'pending',
                'attempt_count'   => 0,
                'next_attempt_at' => now(),
            ]);

        WebhookDelivery::where('subscription_id', $subscription->id)
            ->where('status', 'pending')
            ->each(fn($d) => SendWebhookJob::dispatch($d));

        return response()->json(['requeued' => $count]);
    }

    // История попыток для конкретной доставки
    public function attempts(WebhookDelivery $delivery): JsonResponse
    {
        return response()->json(
            $delivery->attempts()
                ->orderBy('attempt_number')
                ->get(['attempt_number', 'started_at', 'duration_ms',
                       'response_code', 'response_body', 'error_message', 'success'])
        );
    }
}

Пошаговый план внедрения webhook-системы с логированием

Стратегия ротации логов: успешные попытки — 30 дней с телом, затем только метаданные. Неуспешные — 90 дней для аудита. Тело ответа с ошибкой — максимум 2 КБ, бинарные данные не сохраняются.

Почему наша система экономит до 80% времени на отладку?

Обычный лог-файл не даёт контекста: вы видите ошибку, но не знаете, что было до неё. Наша система хранит полную хронологию каждой доставки, связывая все попытки. Это сокращает время расследования с часов до минут. Встроенные агрегаты (среднее число попыток, P95 доставки) позволяют заранее выявлять проблемные интеграции. Сравните: без логирования — ручной поиск по логам сервера, догадки, перезапуск интеграций. С нашей системой — открыл дашборд, отфильтровал по статусу, увидел историю каждой попытки. Нажал «переотправить» — и сбойные события ушли заново. Мы реализуем это на Laravel очередях с PostgreSQL. Результат — экономия до 80% времени на отладку.

Что входит в работу и сроки

• Разработка модуля логирования попыток и повторной отправки.
• Настройка очередей и retry policy.
• Создание дашборда с фильтрацией и агрегатами.
• Документация API и схемы данных.
• Обучение команды работе с системой.
• Техническая поддержка в течение месяца.

Сроки: система логирования попыток и ручная повторная отправка — от 3 до 5 дней. С дашбордом, агрегатами, фильтрацией и retention policy — от 1 до 1.5 недель.

Закажите систему под ключ — свяжитесь с нами для точной оценки вашего проекта. Получите консультацию по внедрению.

Разработка API: REST, GraphQL, WebSocket, tRPC

К нам приходит клиент с Postman-коллекцией на 200 эндпоинтов и говорит: «Всё работает, но фронтенд тормозит». Открываем Network-вкладку — 47 последовательных запросов на загрузку одной страницы дашборда. Каждый ждёт предыдущего. Это не проблема скорости сервера — это проблема архитектуры API. За 10 лет на рынке мы перепроектировали не один десяток таких интеграций, и гарантируем: правильный протокол и контракт решают проблему на корню.

Когда REST перестаёт справляться

REST хорошо работает для простых CRUD-операций. Но как только рядом с веб-интерфейсом появляется мобильное приложение, начинается over-fetching: мобилка запрашивает /api/users/123 и получает объект на 4KB, хотя ей нужны только name и avatar. Умножьте на список из 50 пользователей — 200KB трафика вместо 8KB.

GraphQL решает это через selection sets. Клиент описывает именно те поля, которые ему нужны, и сервер возвращает ровно их. На проекте с React Native + Next.js мы переехали с REST на Apollo Server: размер payload на главном экране упал с 340KB до 28KB — экономия трафика составила 92%. Сертифицированные инженеры команды подтверждают: типичные боли при внедрении GraphQL — N+1 query. Резолвер для поля author у поста вызывает SELECT * FROM users WHERE id = ? для каждого поста в списке. На странице с 20 постами — 21 запрос к базе. Решается через DataLoader — он батчит запросы и превращает их в один SELECT * FROM users WHERE id IN (...).

Что такое tRPC и чем он лучше REST/GraphQL?

Если весь стек на TypeScript (Next.js + Node/Bun), tRPC убирает целый слой проблем. Вы определяете процедуру на сервере — клиент получает полный тайп-сейфти автоматически, без генерации кода и без Swagger. Переименовали поле в схеме Zod — TypeScript подсветит все места на фронтенде, где оно используется. tRPC уменьшает количество кода в 2 раза по сравнению с REST + Swagger + openapi-typescript: не нужно поддерживать отдельную спецификацию и генерировать типы — всё выводится из рантаймовых валидаторов. Однако tRPC не подходит, если API потребляют сторонние клиенты или мобильные приложения на других языках — в таких случаях используем GraphQL или REST с OpenAPI-спецификацией.

WebSocket и реальное время: когда SSE, когда WS?

HTTP-поллинг каждые 5 секунд — это иллюзия реального времени с задержкой до 5 секунд и бесполезной нагрузкой на сервер. Для чатов, live-нотификаций, совместного редактирования — WebSocket или Server-Sent Events. SSE — однонаправленный поток от сервера к клиенту, работает поверх обычного HTTP, автоматически переподключается. Подходит для нотификаций, стриминга данных, прогресс-баров. WebSocket — двунаправленный, нужен для чатов и коллаборативных фич. Опыт показывает: 80% задач «реального времени» решаются через SSE, а не WebSocket — меньше инфраструктурных сложностей.

Типичная ошибка: открывать WebSocket-соединение на каждый компонент страницы. На одном проекте дашборд открывал 12 параллельных WS-соединений. Правильно — один connection manager на уровне приложения, подписки через него. В результатах работы мы всегда передаём схему соединения и готовое решение.

Swagger / OpenAPI как контракт

Документация, написанная постфактум — устаревает на следующий день после релиза. Мы пишем спецификацию OpenAPI 3.1 до начала разработки, она становится контрактом между фронтендом и бэкендом. Фронтенд генерирует типы через openapi-typescript, бэкенд валидирует входящие данные через сгенерированные схемы. Расхождение контракта с реализацией ловится на CI, а не на ревью. Для Laravel — l5-swagger или dedoc/scramble. Для Node.js — @fastify/swagger или Zod + zod-to-openapi.

Как правильно аутентифицировать API?

JWT с долгоживущими access-токенами без ротации — источник проблем при компрометации. Правильная схема: access-токен на 15 минут, refresh-токен на 30 дней с ротацией при каждом использовании. Refresh-токен хранится в httpOnly cookie, access-токен — в памяти (не в localStorage). Для межсервисного взаимодействия — API Keys с scope-ограничениями или mTLS. OAuth 2.0 с PKCE для публичных клиентов (SPA, мобилки).

Версионирование и обратная совместимость

Ломающие изменения в API без версионирования ломают клиентов. Три подхода мы используем в проектах:

Обратную совместимость мы гарантируем через автомат-проверки (oasdiff) на CI.

Как мы разрабатываем API: пошаговый план

1. Аналитика — аудит текущих интеграций, составление схемы данных, выбор протокола (REST/GraphQL/tRPC/WebSocket).
2. Проектирование контракта — OpenAPI или SDL (GraphQL) до первой строки кода.
3. Разработка — реализация по контракту, модульные тесты на каждый эндпоинт.
4. Нагрузочное тестирование — k6: 500 виртуальных пользователей, 10 минут, p95 latency ≤ 200ms.
5. Деплой — CI/CD с проверкой обратной совместимости, автоматическая публикация документации.
6. Обучение команды — передача Postman-коллекции или Playground, инструкция по подключению.

Что входит в работу (deliverables)

• OpenAPI 3.1 спецификация (или SDL для GraphQL).
• Сгенерированные клиентские типы для TypeScript / Dart / Kotlin.
• Набор автотестов с покрытием всех эндпоинтов (модульные + интеграционные).
• Нагрузочные тесты (k6) и отчёт (p50/p95/p99 latency, RPS).
• Документация в Swagger UI / Redoc / GraphiQL.
• Обучение команды (2–4 часа воркшопа).
• Поддержка в течение 30 дней после сдачи (по договору).

Наш опыт

• 10+ лет на рынке разработки API.
• 200+ завершённых проектов (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифицированных инженеров (AWS, Kubernetes, API Design).
• Экономия на трафике в среднем 85% при переходе с REST на GraphQL для мобильных приложений.
• 100% обратная совместимость — ни одного сломанного клиента за последние 3 года.

Сроки

Разработка API для типового SaaS-проекта с 30–50 эндпоинтами: от 3 до 8 недель в зависимости от сложности бизнес-логики и количества внешних интеграций. Миграция существующего REST API на GraphQL — от 2 до 6 недель. Добавление WebSocket-слоя к готовому бэкенду — от 1 до 3 недель. Стоимость рассчитывается индивидуально после аудита. Получите консультацию — свяжитесь с нами, чтобы обсудить ваш проект.