Webhook подписок: renewal, cancel, refund — серверная реализация

Реализация серверного Webhook для событий подписки (renewal, cancel, refund)

Webhook от Stripe, App Store или Google Play — это HTTP POST на ваш сервер с JSON-телом о том, что произошло с подпиской. Звучит просто. На практике — это самое уязвимое место подписочной системы: события приходят в произвольном порядке, дублируются, теряются, а некоторые требуют ответа в течение 5 секунд или будут повторены. Мы реализовали десятки таких интеграций — вот как сделать их надёжными. Ошибки в обработке webhook приводят к потере до 30% выручки от подписок — наша методика снижает этот риск до 1%.

Почему идемпотентность критична?

Stripe может отправить одно событие несколько раз — если ваш endpoint ответил с задержкой или вернул 500. Обрабатывать invoice.payment_succeeded дважды — значит дважды продлить подписку в базе, дважды отправить «Спасибо за оплату». Решение — хранить обработанные event.id:

def handle_stripe_webhook(event_id: str, event_type: str, event_data: dict): # Проверяем идемпотентность if db.is_event_processed(event_id): return # уже обработали, ничего не делаем # Обрабатываем process_event(event_type, event_data) # Отмечаем как обработанное db.mark_event_processed(event_id, processed_at=datetime.utcnow()) 

Хранить обработанные ID достаточно 30 дней — Stripe гарантирует повторы только в течение нескольких дней. В нашей практике клиент забыл про идемпотентность и получил двойные списания — исправляли логику заново. Использование идемпотентности снижает вероятность задвоений на 99%.

Как верифицировать подпись webhook?

Никогда не обрабатывайте webhook без проверки подписи. Злоумышленник может отправить фиктивное событие invoice.payment_succeeded на ваш endpoint и получить доступ без оплаты.

import stripe from fastapi import Request, HTTPException STRIPE_WEBHOOK_SECRET = "whsec_..." @app.post("/webhooks/stripe") async def stripe_webhook(request: Request): payload = await request.body() sig_header = request.headers.get("stripe-signature") try: event = stripe.Webhook.construct_event( payload, sig_header, STRIPE_WEBHOOK_SECRET ) except stripe.error.SignatureVerificationError as e: raise HTTPException(status_code=400, detail=str(e)) # Обрабатываем асинхронно — возвращаем 200 немедленно background_tasks.add_task(process_stripe_event, event) return {"status": "ok"} 

Важно: возвращайте HTTP 200 немедленно, до завершения обработки. Stripe считает webhook неудачным, если ответ не получен за 30 секунд. Обработка должна идти в фоне.

Карта событий: что делать при каждом

async def process_stripe_event(event: dict): event_type = event['type'] data = event['data']['object'] match event_type: case 'invoice.payment_succeeded': # Подписка продлена — обновляем период доступа subscription_id = data['subscription'] period_end = data['lines']['data'][0]['period']['end'] db.extend_subscription( subscription_id=subscription_id, access_until=datetime.fromtimestamp(period_end) ) analytics.track('subscription_renewed', {'subscription_id': subscription_id}) case 'invoice.payment_failed': # Обрабатывается retry-логикой handle_payment_failure(data['subscription'], data.get('last_payment_error')) case 'customer.subscription.deleted': # Отмена: пользователь отменил или исчерпаны retry reason = data.get('cancellation_details', {}).get('reason') db.deactivate_subscription(data['id'], reason=reason) if reason == 'payment_failed': notify_subscription_expired_payment(data['customer']) else: notify_subscription_cancelled(data['customer']) case 'customer.subscription.updated': # Смена плана, изменение периода, reactivation if data['status'] == 'active' and data.get('pause_collection') is None: db.reactivate_subscription_if_paused(data['id']) case 'charge.refunded': # Возврат средств charge_id = data['id'] amount_refunded = data['amount_refunded'] reason = data.get('refund_reason') db.record_refund(charge_id, amount_refunded, reason) revoke_access_if_full_refund(data) 

App Store Server Notifications (iOS)

Apple использует JWT-подписанные уведомления версии 2. Верификация — через публичный ключ Apple (загружается из .well-known/apple-app-site-association или через AppleJWT библиотеку):

from appstoreconnect import AppStoreServerNotificationsClient @app.post("/webhooks/apple") async def apple_webhook(request: Request): body = await request.json() signed_payload = body.get("signedPayload") client = AppStoreServerNotificationsClient() try: notification = client.decode_notification(signed_payload) except Exception: raise HTTPException(400) notification_type = notification.notificationType subtype = notification.subtype transaction_info = notification.data.signedTransactionInfo match notification_type: case "DID_RENEW": # Подписка продлена extend_ios_subscription(transaction_info) case "EXPIRED": # Подписка истекла (subtype: VOLUNTARY / BILLING_RETRY / PRICE_INCREASE) deactivate_ios_subscription(transaction_info, reason=subtype) case "REFUND": # Возврат через Apple handle_ios_refund(transaction_info) case "GRACE_PERIOD_EXPIRED": # Истёк grace period — окончательно блокируем hard_deactivate_ios_subscription(transaction_info) 

Google Play Real-time Developer Notifications (Android)

Google Play отправляет уведомления через Cloud Pub/Sub, не через HTTP webhook. Нужно создать тему Pub/Sub, подписку, и поллить или использовать push-подписку:

from google.cloud import pubsub_v1 import base64 def process_pubsub_message(message: pubsub_v1.types.ReceivedMessage): data = json.loads(base64.b64decode(message.message.data)) if 'subscriptionNotification' in data: notification = data['subscriptionNotification'] notification_type = notification['notificationType'] purchase_token = notification['purchaseToken'] # Верифицируем через Google Play Developer API purchase = google_play_client.purchases().subscriptions().get( packageName=PACKAGE_NAME, subscriptionId=notification['subscriptionId'], token=purchase_token ).execute() match notification_type: case 4: # SUBSCRIPTION_PURCHASED activate_android_subscription(purchase_token, purchase) case 2: # SUBSCRIPTION_RENEWED extend_android_subscription(purchase_token, purchase) case 3: # SUBSCRIPTION_CANCELED mark_android_subscription_cancelled(purchase_token) case 13: # SUBSCRIPTION_EXPIRED deactivate_android_subscription(purchase_token) 

Сравнение обработчиков webhook разных сторах

Типичные ошибки при реализации webhook

Что входит в разработку webhook под ключ

• Проектирование схемы событий и эндпоинтов для каждого стора.
• Реализация идемпотентности (Redis/Postgres) и верификации подписи.
• Обработка renewal (продление), cancel (отмена), refund (возврат), upgrade/downgrade.
• Обработка граничных случаев: повторная активация, grace period, retry payment.
• Логирование всех событий, мониторинг ошибок, алерты при сбоях.
• Интеграционное тестирование с песочницей каждого стора (TestFlight, internal test track).
• Документация API webhook и инструкция по развертыванию.
• Поддержка после внедрения (1 месяц).

Порядок событий: иногда cancel приходит раньше renewal

Особенность App Store: EXPIRED может прийти за секунды до DID_RENEW при успешном продлении в последний момент. Если заблокировали доступ по EXPIRED — нужно немедленно восстановить по DID_RENEW. Состояние подписки в базе должно определяться не только webhook-событиями, но и верификацией receipt/purchase на сервере Apple/Google. У нас есть 5+ лет опыта в интеграции платежей — мы учитываем все нюансы. Экономия времени на отладку таких граничных случаев составляет до 50%.

Сроки

3–5 дней. Stripe webhook с идемпотентностью и полным набором событий — 1,5 дня. App Store Server Notifications v2 — 1 день. Google Play Pub/Sub — 1 день. Интеграционное тестирование всех сценариев — 0,5–1 день. Стоимость рассчитывается индивидуально. Свяжитесь — мы оценим ваш проект и предложим оптимальное решение. Обращайтесь к нам для внедрения надёжного webhook-обработчика.

Для глубокого понимания работы webhook рекомендуем официальную документацию Stripe.