Обзор

• Поддерживать синхронизацию вашего бэкенда с данными о подписках и покупках в реальном времени

• Настраивать автоматизированные рабочие процессы, реагирующие на события подписки

• Отправлять своевременные уведомления подписчикам о проблемах с оплатой или взаимодействовать с ними при отписке.

Поддерживаемые события

Структура вебхука

Заголовки 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", // id клиента в эквайринге
      "email": "user@example.com"
    },
    "user": {
      "id": "cus_customer123", // id пользователя в пейволе
      "metadata": { // метаданные пользователя - paywall.setUserMetadata
	      "some-custom-field": "value" 
      }
    },
    "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
}

Проверка подлинности

Подпись вебхука

Пример проверки подписи

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

• Проверьте логи вебхуков в панели управления

• Убедитесь, что вебхук активен и подписан на нужные события

Можно ли настроить несколько вебхуков?

Как обновить настройки существующего вебхука?

Что делать, если вебхуки приходят дублированно?

Безопасность

• Всегда проверяйте подпись вебхука при использовании секретного ключа

• Используйте HTTPS для всех webhook URL'ов

• Не логируйте полные данные вебхуков в открытом виде

• Ограничьте доступ к webhook endpoint'ам

• Валидируйте данные перед обработкой

Ограничения

• Максимальный размер payload: 1 МБ

• Таймаут: 10 секунд

• Максимальное количество вебхуков на аккаунт: 10

• Ретенция логов: 30 дней

Поддержка

• ID вебхука

• Время события

• Ожидаемое поведение

• Фактическое поведение

• Логи с вашей стороны (если есть)