Налаштування 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.