Webhook-система з логуванням та повторним відправленням

Ви запустили інтеграцію з CRM-партнера. Перші події надходять, але через годину клієнт скаржиться, що не отримав половину сповіщень. Логи мовчать — отримувач відповідав 200, але дані не обробив. Без деталізації кожної спроби з'ясувати причину — ворожіння. Ми розробляємо Webhook-системи з повним логуванням та повторним відправленням: не просто «відправити і забути», а контроль кожної події. 5+ років в інтеграціях B2B, 100+ проектів — гарантуємо прозорість і надійність.

Webhook — це вихідний HTTP-запит, який ви не контролюєте до кінця. Отримувач може повернути 200, не обробивши дані. Може впасти через 9 секунд після отримання. Може пропустити подію без сліду. Без детального логування всіх спроб і можливості ручного повторного відправлення налагодити проблеми з інтеграцією практично неможливо.

Чому логування кожної спроби — основа надійної webhook-системи?

Припустимо, подія впала на третій спробі після таймауту. Якщо не зберігати історію, ви побачите лише фінальний статус. А так — повна картина: перша спроба впала з 500, друга з таймаутом через 8 секунд, третя — 502. Це одразу вказує на проблеми на стороні отримувача. Системи без логування спроб змушують розробників витрачати години на відтворення. Наш підхід скорочує час налагодження в середньому в 5 разів порівняно з традиційним моніторингом.

Які дані ми логуємо і як це реалізовано?

Мінімальний набір даних на кожну спробу доставки:

Зберігаємо спроби окремо від доставок — одна доставка може мати 8 спроб. Це дозволяє бачити повну історію і розуміти, на якому кроці все пішло не так.

CREATE TABLE webhook_attempts ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), delivery_id UUID NOT NULL REFERENCES webhook_deliveries(id) ON DELETE CASCADE, attempt_number INTEGER NOT NULL, started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), duration_ms INTEGER, request_body JSONB, request_headers JSONB, response_code INTEGER, response_headers JSONB, response_body TEXT, -- обрізається до 2000 символів error_message TEXT, success BOOLEAN NOT NULL DEFAULT false ); CREATE INDEX idx_attempts_delivery ON webhook_attempts(delivery_id); CREATE INDEX idx_attempts_started ON webhook_attempts(started_at DESC); 

Реалізація логування:

class WebhookAttemptLogger { public function log( WebhookDelivery $delivery, int $attempt, WebhookAttemptData $data ): WebhookAttempt { return WebhookAttempt::create([ 'delivery_id' => $delivery->id, 'attempt_number' => $attempt, 'started_at' => $data->startedAt, 'duration_ms' => $data->durationMs, 'request_body' => $delivery->payload, 'request_headers' => $data->requestHeaders, 'response_code' => $data->responseCode, 'response_headers' => $data->responseHeaders, 'response_body' => $data->responseBody ? mb_substr($data->responseBody, 0, 2000) : null, 'error_message' => $data->errorMessage, 'success' => $data->success, ]); } } class SendWebhookJob implements ShouldQueue { public function handle( WebhookAttemptLogger $logger ): void { $startedAt = now(); $requestHeaders = $this->buildHeaders(); try { $response = Http::timeout(15) ->withHeaders($requestHeaders) ->post($this->delivery->subscription->endpoint_url, $this->delivery->payload); $durationMs = (int)(microtime(true) * 1000 - $startedAt->timestamp * 1000); $logger->log($this->delivery, $this->delivery->attempt_count, new WebhookAttemptData( startedAt: $startedAt, durationMs: $durationMs, requestHeaders: $requestHeaders, responseCode: $response->status(), responseHeaders: $response->headers(), responseBody: $response->body(), success: $response->successful(), )); if ($response->successful()) { $this->delivery->markDelivered(); } else { $this->delivery->scheduleRetry(); } } catch (\Throwable $e) { $durationMs = (int)(microtime(true) * 1000 - $startedAt->timestamp * 1000); $logger->log($this->delivery, $this->delivery->attempt_count, new WebhookAttemptData( startedAt: $startedAt, durationMs: $durationMs, requestHeaders: $requestHeaders, errorMessage: get_class($e) . ': ' . $e->getMessage(), success: false, )); $this->delivery->scheduleRetry(); } } } 

Як організовано ручне повторне відправлення?

Адміністратор або розробник повинні вміти переслати будь-яку подію без зміни коду. Це критично при налагодженні інтеграцій та відновленні після збоїв.

class WebhookDeliveryController extends Controller { // Повторити конкретну доставку public function resend(WebhookDelivery $delivery): JsonResponse { abort_if( $delivery->status === 'delivered', 422, 'Delivery already succeeded' ); $delivery->update([ 'status' => 'pending', 'attempt_count' => 0, 'next_attempt_at' => now(), ]); SendWebhookJob::dispatch($delivery); return response()->json(['queued' => true]); } // Повторити всі невдалі доставки підписки public function resendFailed(WebhookSubscription $subscription): JsonResponse { $count = WebhookDelivery::where('subscription_id', $subscription->id) ->where('status', 'failed') ->count(); WebhookDelivery::where('subscription_id', $subscription->id) ->where('status', 'failed') ->update([ 'status' => 'pending', 'attempt_count' => 0, 'next_attempt_at' => now(), ]); WebhookDelivery::where('subscription_id', $subscription->id) ->where('status', 'pending') ->each(fn($d) => SendWebhookJob::dispatch($d)); return response()->json(['requeued' => $count]); } // Історія спроб для конкретної доставки public function attempts(WebhookDelivery $delivery): JsonResponse { return response()->json( $delivery->attempts() ->orderBy('attempt_number') ->get(['attempt_number', 'started_at', 'duration_ms', 'response_code', 'response_body', 'error_message', 'success']) ); } } 

Покроковий план впровадження webhook-системи з логуванням

Стратегія ротації логів: успішні спроби — 30 днів з тілом, потім лише метадані. Неуспішні — 90 днів для аудиту. Тіло відповіді з помилкою — максимум 2 КБ, бінарні дані не зберігаються.

Чому наша система економить до 80% часу на налагодження?

Звичайний лог-файл не дає контексту: ви бачите помилку, але не знаєте, що було до неї. Наша система зберігає повну хронологію кожної доставки, зв'язуючи всі спроби. Це скорочує час розслідування з годин до хвилин. Вбудовані агрегати (середня кількість спроб, P95 доставки) дозволяють заздалегідь виявляти проблемні інтеграції. Порівняйте: без логування — ручний пошук по логах сервера, здогадки, перезапуск інтеграцій. З нашою системою — відкрив дашборд, відфільтрував за статусом, побачив історію кожної спроби. Натиснув «переслати» — і збійні події пішли заново. Ми реалізуємо це на Laravel чергах з PostgreSQL. Результат — економія до 80% часу на налагодження.

Що входить в роботу та терміни

• Розробка модуля логування спроб і повторного відправлення.
• Налаштування черг і retry policy.
• Створення дашборда з фільтрацією та агрегатами.
• Документація API та схеми даних.
• Навчання команди роботі з системою.
• Технічна підтримка протягом місяця.

Терміни: система логування спроб і ручне повторне відправлення — від 3 до 5 днів. З дашбордом, агрегатами, фільтрацією та retention policy — від 1 до 1.5 тижнів.

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