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

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

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

Що логувати за кожну спробу

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

Схема таблиці спроб

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);

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

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

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'])
        );
    }
}

Дашборд доставок

Для операційного моніторингу потрібен інтерфейс з фільтрацією по:

• Статусу (pending, delivered, failed)
• Типу подій
• Підписці / споживачу
• Часовому діапазону

Корисні агрегати в PostgreSQL:

-- Статистика за останні 24 години
SELECT
  event_type,
  COUNT(*) FILTER (WHERE status = 'delivered') AS delivered,
  COUNT(*) FILTER (WHERE status = 'failed')    AS failed,
  COUNT(*) FILTER (WHERE status = 'pending')   AS pending,
  ROUND(AVG(attempt_count), 2)                 AS avg_attempts,
  PERCENTILE_CONT(0.95) WITHIN GROUP (
    ORDER BY EXTRACT(EPOCH FROM (delivered_at - created_at))
  ) AS p95_delivery_seconds
FROM webhook_deliveries
WHERE created_at > NOW() - INTERVAL '24 hours'
GROUP BY event_type
ORDER BY failed DESC;

Термін зберігання логів

Спроби доставки займають місце. Стратегія ротації:

• Успішні спроби—зберігати 30 днів, потім видалити тіло запиту, залишити метадані
• Невдалі—зберігати 90 днів (потрібні для аудиту інтеграцій)
• Тіло відповіді з помилкою—максимум 2 КБ, не зберігати бінарні дані

Терміни

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