Stripe Webhooks: полное руководство по настройке и безопасности

Что такое webhook в Stripe, как правильно его настроить, верифицировать подпись и избежать типичных ошибок при обработке событий оплаты.

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.