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

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

Webhook без retry—це просто HTTP-запит, який ви відправили і забули. Реальні системи падають: ендпоїнт отримувача недоступний, таймаут, помилки 500. Гарантія доставки означає, що подія дійде до отримувача, навіть якщо той був недоступний кілька годин.

Принципи надійної доставки

At-least-once delivery: webhook може бути доставлений більше одного разу. Отримувач повинен бути ідемпотентним—повторна обробка однієї подій не має дублювати ефект.

Черга як буфер: відправлення webhook не відбувається безпосередньо з обробника подій. Подія записується в чергу, воркер читає і відправляє. Якщо відправлення не вдалось—подія повертається в чергу.

Exponential 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';

Алгоритм retry з backoff

Експоненціальний 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)
    # Обмежено 1 годиною
    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 зобов'язаний обробляти повтори. Мінімальний захист:

# 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:

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: якщо зростає—воркерів недостатньо

Терміни

Базова система з retry/backoff: 3–5 днів. З моніторингом, дашбордом доставок і сповіщеннями про збої: 1–1.5 тижня.