Серверний 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.