Stripe Webhooks: повний посібник з налаштування та безпеки

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

Чому не можна обійтися без webhooks

Редирект після оплати — ненадійний спосіб підтвердження. Клієнт міг закрити вкладку, втратити з’єднання або зіткнутися із затримкою браузера. Webhook приходить напряму від Stripe на ваш сервер і не залежить від дій користувача.

Ключові події для обробки:

• payment_intent.succeeded — платіж пройшов, можна видавати товар або доступ
• payment_intent.payment_failed — оплата не вдалася, повідомити клієнта
• customer.subscription.deleted — підписку скасовано
• invoice.payment_failed — не вдалося списати оплату за підписку
• charge.dispute.created — відкрито чарджбек, потрібно терміново реагувати

Як зареєструвати endpoint

У Dashboard Stripe перейдіть до Developers → Webhooks → Add endpoint. Вкажіть URL вашого обробника (наприклад https://yourdomain.com/webhooks/stripe) і виберіть події для підписки.

Для локальної розробки використовуйте Stripe CLI:

stripe listen --forward-to localhost:3000/webhooks/stripe

Верифікація підпису — обов’язковий крок

Stripe підписує кожен webhook заголовком Stripe-Signature. Перевіряйте його перед будь-якою обробкою даних:

$payload = @file_get_contents('php://input');
$sig_header = $_SERVER['HTTP_STRIPE_SIGNATURE'];
$secret = getenv('STRIPE_WEBHOOK_SECRET');

try {
    $event = \Stripe\Webhook::constructEvent(
        $payload, $sig_header, $secret
    );
} catch (\Stripe\Exception\SignatureVerificationException $e) {
    http_response_code(400);
    exit();
}

Без цієї перевірки будь-який зловмисник може надіслати підроблений запит на ваш endpoint.

Ідемпотентність обробників

Stripe може надіслати одну й ту саму подію кілька разів у разі мережевих збоїв. Зберігайте event.id у базі даних і перевіряйте перед обробкою — це захистить від дублювання замовлень і повторного нарахування бонусів.

Типові помилки

• Повернення статусу 200 лише після завершення бізнес-логіки (Stripe вважає webhook невдалим, якщо відповідь приходить довше 30 секунд — приймайте подію одразу, логіку виносьте в чергу)
• Відсутність retry-логіки на боці сервера
• Обробка подій без перевірки підпису
• Ігнорування charge.dispute.created (втрата чарджбеку без відповіді = автоматична поразка)

Моніторинг webhook-подій

У Dashboard Stripe розділ Developers → Webhooks показує історію відправлень, статуси відповідей і дозволяє вручну повторити будь-яку подію. Налаштуйте алерти на невдалі доставки.

Правильна обробка вебхуків — основа надійної платіжної інфраструктури. Якщо потрібна допомога з інтеграцією або готовий прогрітий Stripe-акаунт — звертайтеся до нас у Telegram.

Webhooks простіше тримати в робочому контурі, якщо процесинг уже зібраний: процесинг Stripe під ключ.