Налаштування 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-системи під ваш проєкт.