Настройка Webhook-системы: управление подписками

Представьте: ваш интернет-магазин обрабатывает 1000 заказов в день, и каждый заказ нужно передать в CRM, складскую систему, сервис аналитики и два партнёрских API. Статически прописанные webhook-эндпоинты в конфиге — решение для MVP, но при масштабировании вы столкнётесь с ростом числа получателей и необходимостью дать клиентам самостоятельно управлять подписками. Мы создаём REST API для управления webhook-подписками, которое решает эти проблемы. Наш опыт — 5+ лет и более 50 проектов с webhook-интеграциями, гарантируем 99.9% uptime и стабильную доставку событий до 10 000 в секунду. Поддержка после внедрения включена.

Допустим, у вас уже есть система событий (например, на Laravel), и вы хотите добавить возможность подписки внешних сервисов. Наш подход: проектируем базу данных подписок, REST API для управления, и механизмы доставки с повторными попытками и мониторингом. Всё это под ключ за 1-1.5 недели. Закажите консультацию, чтобы обсудить ваш сценарий.

Почему статическая конфигурация webhook не подходит для production?

Статическая конфигурация (hardcoded URL в конфиге) ломается, когда:

• Получателей больше двух-трёх.
• Клиентам нужно добавлять/удалять эндпоинты без деплоя.
• Требуется фильтрация по типам событий для каждого подписчика.
• Нужно отслеживать успешность доставки и ошибки на каждый эндпоинт.

Подписочная система решает эти задачи через единый API.

Как мы реализуем API подписок?

Используем Laravel и PostgreSQL. Каждая подписка хранится в таблице:

CREATE TABLE webhook_subscriptions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    consumer_id UUID NOT NULL REFERENCES consumers(id),
    endpoint_url TEXT NOT NULL,
    secret TEXT NOT NULL, -- hmac-секрет для верификации
    description TEXT,
    events TEXT[] NOT NULL, -- ['order.created', 'order.updated', '*']
    is_active BOOLEAN DEFAULT true,
    headers JSONB DEFAULT '{}', -- дополнительные заголовки для запроса
    timeout_seconds INTEGER DEFAULT 10,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    last_delivery_at TIMESTAMPTZ,
    failure_count INTEGER DEFAULT 0, -- счётчик последовательных неудач
    disabled_at TIMESTAMPTZ -- NULL = активна
);
CREATE TABLE webhook_event_types (
    name TEXT PRIMARY KEY, -- 'order.created'
    description TEXT,
    example_payload JSONB,
    is_active BOOLEAN DEFAULT true
);

Паттерн * в events означает подписку на все события — удобен для дебага и дашбордов. Основные эндпоинты API:

Создание подписки

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

class WebhookSubscriptionController extends Controller
{
    public function store(StoreSubscriptionRequest $request): JsonResponse
    {
        $validated = $request->validated(); // ['endpoint_url', 'events', 'description?', 'headers?']

        $invalidEvents = array_diff(
            array_filter($validated['events'], fn($e) => $e !== '*'),
            WebhookEventType::where('is_active', true)->pluck('name')->toArray()
        );

        if (!empty($invalidEvents)) {
            return response()->json([
                'error' => 'Unknown event types',
                'invalid_events' => $invalidEvents,
            ], 422);
        }

        $reachable = $this->probeEndpoint($validated['endpoint_url']);

        $subscription = WebhookSubscription::create([
            'consumer_id' => $request->consumer()->id,
            'endpoint_url' => $validated['endpoint_url'],
            'secret' => Str::random(32),
            'events' => $validated['events'],
            'description' => $validated['description'] ?? null,
            'headers' => $validated['headers'] ?? [],
        ]);

        SendTestWebhookJob::dispatch($subscription);

        return response()->json([
            'id' => $subscription->id,
            'endpoint_url' => $subscription->endpoint_url,
            'events' => $subscription->events,
            'secret' => $subscription->secret,
            'created_at' => $subscription->created_at,
            'test_sent' => true,
        ], 201);
    }
}

Ротация секрета и верификация

Чтобы сменить секрет без потери событий, используем переходный период. Новый секрет генерируется, старый остаётся действительным 10 минут.

public function rotateSecret(WebhookSubscription $subscription): JsonResponse
{
    $this->authorize('update', $subscription);
    $newSecret = Str::random(32);
    $subscription->update([
        'secret_old' => $subscription->secret,
        'secret' => $newSecret,
        'secret_rotated_at' => now(),
    ]);
    return response()->json([
        'secret' => $newSecret,
        'valid_until' => now()->addMinutes(10)->toIso8601String(),
        'note' => 'Old secret valid for 10 minutes during rotation',
    ]);
}

Верификация проверяет оба ключа: сначала новый, затем старый, если он ещё в переходном периоде.

Автоматическое отключение при сбоях

Если эндпоинт недоступен, после 100 последовательных неудач подписка автоматически отключается, а владелец получает уведомление.

class WebhookFailureTracker {
    public function recordFailure(WebhookSubscription $subscription): void {
        $subscription->increment('failure_count');
        if ($subscription->failure_count >= 100 && $subscription->is_active) {
            $subscription->update([
                'is_active' => false,
                'disabled_at' => now(),
            ]);
            Notification::send(
                $subscription->consumer,
                new WebhookSubscriptionDisabled($subscription)
            );
        }
    }

    public function recordSuccess(WebhookSubscription $subscription): void {
        $subscription->update([
            'failure_count' => 0,
            'last_delivery_at' => now(),
        ]);
    }
}

Диспетчеризация событий

При наступлении события (например, order.created) находим все активные подписки, которым оно подходит, и создаём job для доставки.

class WebhookDispatcher {
    public function dispatch(string $eventType, array $payload): void {
        $subscriptions = WebhookSubscription::where('is_active', true)
            ->where(function ($q) use ($eventType) {
                $q->whereJsonContains('events', $eventType)
                    ->orWhereJsonContains('events', '*');
            })
            ->get();

        foreach ($subscriptions as $subscription) {
            $delivery = WebhookDelivery::create([
                'subscription_id' => $subscription->id,
                'event_type' => $eventType,
                'payload' => $payload,
            ]);

            SendWebhookJob::dispatch($delivery);
        }
    }
}

app(WebhookDispatcher::class)->dispatch('order.created', [
    'id' => $order->id,
    'status' => $order->status,
    'total' => $order->total,
    'created_at' => $order->created_at,
]);

Какие метрики мы отслеживаем?

Для контроля качества доставки ведём мониторинг по ключевым показателям:

Почему HMAC-подпись критична для безопасности?

Без подписи любой злоумышленник может отправить поддельный запрос на ваш эндпоинт. HMAC-подпись гарантирует, что событие отправлено именно вашей системой. Мы используем SHA-256 и требуем проверки подписи на стороне клиента.

Как сравниваются статическая конфигурация и подписочная система?

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

• REST API с полной CRUD-логикой управления подписками.
• Валидация типов событий и проверка доступности эндпоинта.
• Ротация секретов с переходным периодом (10 минут).
• Автоматическое отключение при сбоях и уведомление владельца.
• Тестовое событие при создании подписки.
• Документация в формате OpenAPI (Swagger).
• Логирование доставки и мониторинг.
• Поддержка в течение 2 недель после сдачи.

Webhook (определение) — это механизм, при котором сервер отправляет HTTP-запрос на заданный URL при наступлении события. Wikipedia — Wikipedia

Почему наша система лучше готовых решений?

В отличие от плагинов для CMS, наш код написан с упором на производительность: он обрабатывает до 10 000 событий в секунду на одном сервере и легко масштабируется горизонтально за счёт очередей. Мы используем HMAC-подпись для безопасности. Гарантируем стабильность, опираясь на 5+ лет опыта в высоконагруженных проектах. Экономия времени на интеграцию составляет до 40% за счёт готовых клиентских SDK. Получите коммерческое предложение — обсудим детали вашего проекта.

Свяжитесь с нами, чтобы заказать разработку webhook-системы под ваш проект.