Monetize.software может отправлять вам уведомления каждый раз, когда в вашем приложении происходит событие, и отслеживать изменения состояния для ваших подписчиков.
С интегрированными вебхуками вы сможете:
- Поддерживать синхронизацию вашего бэкенда с данными о подписках и покупках в реальном времени
- Настраивать автоматизированные рабочие процессы, реагирующие на события подписки
- Отправлять своевременные уведомления подписчикам о проблемах с оплатой или взаимодействовать с ними при отписке.
Поддерживаемые события
Событие | Описание |
payment.completed | Успешно завершенный платеж (разовый или первый платеж подписки) |
subscription.created | Создание новой подписки |
subscription.updated | Обновление подписки (изменение плана, статуса и т.д.) |
subscription.cancelled | Отмена подписки |
refund.created | Создание возврата средств |
Структура вебхука
Заголовки HTTP
Content-Type: application/json User-Agent: Monetize-Webhooks/1.0 X-Monetize-Signature: sha256=<signature> (если настроен секретный ключ)
Структура payload
{ "id": "evt_1234567890_abcdef123", "type": "payment.completed", "created_at": "2024-01-15T12:30:45.000Z", "data": { "price": { "id": "cus_customer123", // Internal price id "unit_amount": 2000, // Сумма в центах "interval": "year" // План - week, month, year, lifetime }, "customer": { "id": "cus_customer123", "email": "user@example.com" }, "paywall": { "id": "123", "name": "Premium Plan" }, "acquiring": { "id": "acq_456", "provider": "stripe" } } }
Дополнительные поля для платежей
"payment": { "id": "pi_payment123", "status": "succeeded", "payment_method": "card" }
Дополнительные поля для подписок
"subscription": { "id": "sub_subscription123", "status": "active", "current_period_start": "2024-01-15T12:30:45.000Z", "current_period_end": "2024-02-15T12:30:45.000Z" }
Дополнительные поля для возвратов
"refund": { "id": "re_refund123", "reason": "requested_by_customer", "amount": 2999 }
Проверка подлинности
Подпись вебхука
Если вы настроили секретный ключ, каждый вебхук будет содержать заголовок
X-Monetize-Signature
с HMAC SHA256 подписью тела запроса.Пример проверки подписи
Python
import hmac import hashlib def verify_webhook_signature(payload, signature, secret): expected_signature = hmac.new( secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256 ).hexdigest() # Убираем префикс "sha256=" из заголовка signature = signature.replace('sha256=', '') return hmac.compare_digest(expected_signature, signature) # Использование is_valid = verify_webhook_signature( request.body, request.headers.get('X-Monetize-Signature'), 'your_webhook_secret' )
Node.js
const crypto = require('crypto'); function verifyWebhookSignature(payload, signature, secret) { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); // Убираем префикс "sha256=" из заголовка signature = signature.replace('sha256=', ''); return crypto.timingSafeEqual( Buffer.from(expectedSignature), Buffer.from(signature) ); } // Использование const isValid = verifyWebhookSignature( req.body, req.headers['x-monetize-signature'], 'your_webhook_secret' );
PHP
function verifyWebhookSignature($payload, $signature, $secret) { $expectedSignature = hash_hmac('sha256', $payload, $secret); // Убираем префикс "sha256=" из заголовка $signature = str_replace('sha256=', '', $signature); return hash_equals($expectedSignature, $signature); } // Использование $isValid = verifyWebhookSignature( file_get_contents('php://input'), $_SERVER['HTTP_X_MONETIZE_SIGNATURE'], 'your_webhook_secret' );
Обработка вебхуков
Требования к endpoint'у
- HTTPS: Вебхуки отправляются только на HTTPS URL'ы
- Статус ответа: Ваш endpoint должен возвращать HTTP статус 200-299 для успешной обработки
- Таймаут: Время ожидания ответа составляет 10 секунд
- Идемпотентность: Будьте готовы к получению дублирующихся событий
Рекомендации по обработке
const express = require('express'); const app = express(); app.use(express.json()); app.post('/webhooks/monetize', async (req, res) => { try { // Проверка подписи const signature = req.headers['x-monetize-signature']; if (signature && !verifyWebhookSignature( JSON.stringify(req.body), signature, 'your_secret' )) { return res.status(401).json({ error: 'Invalid signature' }); } // Обработка события const event = req.body; switch (event.type) { case 'payment.completed': await handlePaymentCompleted(event.data); break; case 'subscription.created': await handleSubscriptionCreated(event.data); break; // ... другие события } res.json({ status: 'success' }); } catch (err) { console.error(`Webhook error: ${err}`); res.status(500).json({ error: 'Internal error' }); } }); async function handlePaymentCompleted(data) { // Ваша логика обработки платежа console.log(`Payment completed: ${data.id}`); // Например, активация доступа пользователя } async function handleSubscriptionCreated(data) { // Ваша логика обработки создания подписки console.log(`Subscription created: ${data.subscription.id}`); // Например, предоставление доступа к премиум функциям } app.listen(3000, () => { console.log('Webhook server is running on port 3000'); });
Механизм повторных попыток
Система автоматически повторяет отправку вебхука при неудаче:
- Количество попыток: 5 попыток
- Интервалы: 5, 10, 20, 40, 80 минут (увеличивающиеся задержки)
- Условия повтора: HTTP статус 5xx или таймаут соединения
- После 5 неудачных попыток: отправка уведомлений прекращается
Логирование
Все попытки отправки вебхуков логируются, включая:
- Время отправки
- HTTP статус ответа
- Тело ответа (первые 1000 символов)
- Сообщения об ошибках
- Номер попытки
Логи доступны в панели управления в разделе Настройки → Вебхуки → выбрать конкретный вебхук.
FAQ
Что делать, если вебхуки не приходят?
- Проверьте, что URL доступен и возвращает статус 200
- Убедитесь, что используется HTTPS
- Проверьте логи вебхуков в панели управления
- Убедитесь, что вебхук активен и подписан на нужные события
Можно ли настроить несколько вебхуков?
Да, вы можете создать несколько вебхуков с разными URL и событиями.
Как обновить настройки существующего вебхука?
В разделе Настройки → Вебхуки нажмите на иконку редактирования рядом с нужным вебхуком.
Что делать, если вебхуки приходят дублированно?
Это нормальное поведение при повторных попытках. Реализуйте идемпотентную обработку, используя поле
id
события для дедупликации.Безопасность
- Всегда проверяйте подпись вебхука при использовании секретного ключа
- Используйте HTTPS для всех webhook URL'ов
- Не логируйте полные данные вебхуков в открытом виде
- Ограничьте доступ к webhook endpoint'ам
- Валидируйте данные перед обработкой
Ограничения
- Максимальный размер payload: 1 МБ
- Таймаут: 10 секунд
- Максимальное количество вебхуков на аккаунт: 10
- Ретенция логов: 30 дней
Поддержка
При возникновении проблем с вебхуками обращайтесь в техническую поддержку, указав:
- ID вебхука
- Время события
- Ожидаемое поведение
- Фактическое поведение
- Логи с вашей стороны (если есть)