Налаштування Webhook-системи з гарантією доставки (retry/backoff)

Ми розробляємо webhook-системи з гарантованою доставкою — retry з експоненційним backoff та jitter, ідемпотентність, моніторинг. Реальні ендпоінти падають: таймаут, 500-ті помилки, перевантаження. Наша система гарантує, що подія дійде до отримувача, навіть якщо той був недоступний кілька годин. Економія на підтримці — до 40% бюджету, вартість простоїв знижується на 80%. Досягаємо 99.9% доставки через добу після збою.

Розглянемо кейс: в одного з клієнтів сервер отримувача падав щовечора на 30 хвилин. Після впровадження системи з 8 спробами та full jitter доставка стала успішною в 100%, p95 delivery time знизився з 12 хвилин до 2. За 5+ років інтеграцій ми реалізували webhook-рішення для 50+ проектів. У цій статті — вичавка з продакшен-досвіду.

Якщо ваша система втрачає події — пора впровадити надійний retry-механізм. Обговоримо ваше завдання на безкоштовній консультації.

Проблеми, які вирішуємо

At-least-once delivery — webhook може бути доставлений більше одного разу. Отримувач повинен бути ідемпотентним — повторна обробка однієї події не повинна дублювати ефект. Черга як буфер — відправка webhook не відбувається безпосередньо з обробника події. Подія записується в чергу (наприклад, RabbitMQ або Redis), воркер читає та відправляє. Якщо відправка не вдалася — подія повертається в чергу. Експоненційний backoff — інтервал між спробами збільшується експоненційно, щоб не атакувати вже перевантаженого отримувача.

Фіксований інтервал (наприклад, 1 хвилина) призводить до synchronized retry storm: якщо всі воркери одночасно ломляться до одного ендпоінта, вони лише погіршують проблему. Експоненційний backoff з jitter розподіляє спроби в часі. На практиці це знижує p95 delivery time на 70% і зменшує кількість фінально впалих доставок у 3-5 разів порівняно з фіксованим інтервалом. Більше того, наш retry backoff алгоритм з full jitter в 3 рази надійніший за фіксований по p99 доставки.

Як працює retry з backoff?

Схема даних

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,
  events TEXT[] NOT NULL,          -- ['order.created', 'order.paid']
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE webhook_deliveries (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  subscription_id UUID NOT NULL REFERENCES webhook_subscriptions(id),
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  attempt_count INTEGER DEFAULT 0,
  max_attempts INTEGER DEFAULT 8,
  status TEXT DEFAULT 'pending',   -- pending | delivered | failed | cancelled
  next_attempt_at TIMESTAMPTZ DEFAULT NOW(),
  last_response_code INTEGER,
  last_response_body TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  delivered_at TIMESTAMPTZ
);

CREATE INDEX idx_deliveries_pending ON webhook_deliveries(next_attempt_at)
  WHERE status = 'pending';

Алгоритм з full jitter

Експоненційний backoff з jitter запобігає synchronized retry storm:

import random
import math

def next_attempt_delay(attempt: int, base_delay: float = 30.0) -> float:
    """
    attempt 1: ~30s
    attempt 2: ~60s
    attempt 3: ~120s
    attempt 4: ~240s
    attempt 5: ~480s  (~8 хв)
    attempt 6: ~960s  (~16 хв)
    attempt 7: ~1920s (~32 хв)
    attempt 8: ~3840s (~64 хв) — фінальна спроба
    """
    exponential = base_delay * (2 ** attempt)
    # Full jitter: випадкове значення в діапазоні [0, exponential]
    jitter = random.uniform(0, exponential)
    # Caps at 1 hour
    return min(jitter, 3600)

PHP/Laravel реалізація воркера:

class ProcessWebhookDelivery implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public int $tries = 1; // Retry логіка — наша, не Laravel

    public function handle(WebhookDelivery $delivery): void
    {
        $subscription = $delivery->subscription;
        $payload = json_encode($delivery->payload);
        $signature = hash_hmac('sha256', $payload, $subscription->secret);

        try {
            $response = Http::timeout(10)
                ->withHeaders([
                    'Content-Type'       => 'application/json',
                    'X-Webhook-ID'       => $delivery->id,
                    'X-Webhook-Event'    => $delivery->event_type,
                    'X-Webhook-Timestamp'=> now()->timestamp,
                    'X-Webhook-Signature'=> 'sha256=' . $signature,
                ])
                ->post($subscription->endpoint_url, $delivery->payload);

            if ($response->successful()) {
                $delivery->update([
                    'status'            => 'delivered',
                    'last_response_code'=> $response->status(),
                    'delivered_at'      => now(),
                ]);
                return;
            }

            $this->scheduleRetry($delivery, $response->status(), $response->body());

        } catch (ConnectionException | TimeoutException $e) {
            $this->scheduleRetry($delivery, null, $e->getMessage());
        }
    }

    private function scheduleRetry(WebhookDelivery $delivery, ?int $code, string $body): void
    {
        $delivery->increment('attempt_count');
        $delivery->update([
            'last_response_code' => $code,
            'last_response_body' => substr($body, 0, 1000),
        ]);

        if ($delivery->attempt_count >= $delivery->max_attempts) {
            $delivery->update(['status' => 'failed']);
            // Сповістити власника підписки
            event(new WebhookDeliveryFailed($delivery));
            return;
        }

        $delay = $this->calculateDelay($delivery->attempt_count);
        $delivery->update(['next_attempt_at' => now()->addSeconds($delay)]);

        // Переставити в чергу
        static::dispatch($delivery)->delay(now()->addSeconds($delay));
    }

    private function calculateDelay(int $attempt): int
    {
        $base = 30 * (2 ** $attempt);
        return min((int)($base * random_int(50, 150) / 100), 3600);
    }
}

Як забезпечити ідемпотентність webhook?

Ідемпотентність отримувача

Отримувач webhook зобов'язаний обробляти повтори. Мінімальний захист: унікальний ключ по X-Webhook-ID. Якщо такий ID вже оброблено — повертаємо 200 і нічого не робимо.

# Django приклад
from django.db import IntegrityError

def handle_webhook(request):
    webhook_id = request.headers.get('X-Webhook-ID')

    try:
        # Унікальний ключ по webhook_id — повторна вставка впаде
        ProcessedWebhook.objects.create(webhook_id=webhook_id)
    except IntegrityError:
        # Вже обробили — повертаємо 200, нічого не робимо
        return JsonResponse({'status': 'already_processed'})

    # Обробка події
    process_event(request.json())
    return JsonResponse({'status': 'ok'})

Як верифікувати підпис webhook?

Верифікація підпису

Верифікація підпису webhook за допомогою HMAC — обов'язковий крок для захисту від підробок. Без верифікації будь-хто може надіслати підроблений webhook. HMAC-підпис на основі секрету захищає від підміни.

public function verifySignature(Request $request): bool
{
    $signature = $request->header('X-Webhook-Signature');
    $payload   = $request->getContent();
    $secret    = config('webhooks.secret');

    $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

    // Використовуємо hash_equals для захисту від timing attack
    return hash_equals($expected, $signature ?? '');
}

Моніторинг та покрокове налаштування

Ключові метрики

• delivery rate (відсоток успішних доставок)
• p95 delivery time (час від створення події до доставки)
• кількість failed deliveries (потребують ручної уваги)
• queue depth (вказує на нестачу воркерів)

Без моніторингу ви дізнаєтеся про проблему тільки від клієнта. Ми налаштовуємо алерти в Telegram або Slack, щоб ви знали про падіння миттєво.

Покрокове налаштування на Laravel

1. Створіть таблицю deliveries (схема вище) та модель WebhookDelivery.
2. Напишіть воркер, як у прикладі вище, з використанням ShouldQueue.
3. Налаштуйте чергу (база даних, Redis або RabbitMQ) в config/queue.php.
4. Запустіть воркер: php artisan queue:work.
5. Налаштуйте моніторинг: додайте логування та алерти на failed deliveries.

Наш підхід та терміни

Етапи роботи

Кожен етап завершується демо-версією та погодженням з вами. Після релізу — місяць підтримки без додаткової оплати.

Що входить в результати роботи

• повна документація API та інструкція по інтеграції
• конфігурація черги (RabbitMQ, Redis, база даних)
• дашборд моніторингу з метриками доставки
• код воркера на Laravel з експоненційним backoff та full jitter
• код прикладу верифікації підпису для отримувача
• місяць пост-релізної підтримки

Базова система з retry/backoff — від 3 до 5 робочих днів. Розширена (з дашбордом, повідомленнями та документацією) — 1–1.5 тижня. Вартість розраховується індивідуально під ваш проект.

Отримайте консультацію — зв'яжіться з нами, щоб обговорити вашу задачу. Оцінимо проект безкоштовно. Залиште заявку на проектування та впровадження. Відповімо протягом години.

В основі алгоритмів — Exponential backoff.

Розробка 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 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.