Настройка 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.