Вебхуки

Вебхуки для уведомления о событиях в системе.

Настройка:

1. Перейдите в Дэшборд автора → Настройки (меню три точки) → Раздел API-ключи

2. Сгенерируйте API-ключ, если ещё не сделали это

3. Укажите URL вашего вебхука в настройках вебхуков

Проверка подписи: Каждый запрос содержит заголовок trbt-signature с HMAC-SHA256 подписью тела запроса, подписанного вашим API-ключом.

Повторные попытки: При ошибке доставки система повторяет попытки через 5мин, 15мин, 30мин, 1ч, 10ч.

Тип подписки (payload.type) в событиях подписок:

• regular — обычная платная подписка (оформление обычной подписки или продление)

• gift — подарочная подписка (покупка подарка)

• trial — пробная подписка (активация)

Переходы типов: При продлении gift или trial следующая подписка становится regular и это отражается в событии renewed_subscription.

Новая подписка

Уведомление о покупке подписки пользователем

Payload

application/json

namestring · enumRequiredExample: new_subscriptionPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "new_subscription",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "subscription_name": "Поддержите творчество 🌟",
    "subscription_id": 1644,
    "period_id": 1547,
    "period": "monthly",
    "price": 1000,
    "amount": 700,
    "currency": "eur",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "channel_id": 614,
    "channel_name": "lbs",
    "expires_at": "2025-04-20T01:15:57.305733Z",
    "type": "regular"
  }
}

Отмена подписки

Уведомление об отмене подписки пользователем

Payload

application/json

namestring · enumRequiredExample: cancelled_subscriptionPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-21T11:20:44.013969Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-21T11:20:44.527657077Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "cancelled_subscription",
  "created_at": "2025-03-21T11:20:44.013969Z",
  "sent_at": "2025-03-21T11:20:44.527657077Z",
  "payload": {
    "subscription_name": "Присоединяйтесь к закрытому клубу 🎉",
    "subscription_id": 1646,
    "period_id": 1549,
    "period": "monthly",
    "price": 1000,
    "amount": 1000,
    "currency": "eur",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "channel_id": 614,
    "channel_name": "lbs",
    "cancel_reason": "",
    "expires_at": "2025-03-20T11:13:44.737Z",
    "type": "regular"
  }
}

Продление подписки

Уведомление о продлении подписки

Payload

application/json

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-21T11:20:44.013969Z

namestring · enumRequiredExample: renewed_subscriptionPossible values:

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-21T11:20:44.527657077Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "created_at": "2025-03-21T11:20:44.013969Z",
  "name": "renewed_subscription",
  "payload": {
    "subscription_name": "Поддержите творчество 🌟",
    "subscription_id": 1644,
    "period_id": 1547,
    "period": "monthly",
    "price": 1000,
    "amount": 700,
    "currency": "eur",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "email": "[email protected]",
    "web_app_link": "https://t.me/metal3devbot/app?startapp=syX",
    "channel_id": 614,
    "channel_name": "lbs",
    "expires_at": "2025-04-20T01:15:57.305733Z",
    "type": "regular"
  },
  "sent_at": "2025-03-21T11:20:44.527657077Z"
}

Создан физический заказ

Уведомление о создании нового физического заказа

Payload

application/json

namestring · enumRequiredExample: physical_order_createdPossible values:

created_atstring · date-timeRequired

Время создания события

sent_atstring · date-timeRequired

Время отправки события

Responses

200

Вебхук успешно обработан

No content

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "physical_order_created",
  "created_at": "2026-02-02T14:18:03.017Z",
  "sent_at": "2026-02-02T14:18:03.017Z",
  "payload": {
    "order_id": 12345,
    "status": "pending",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "products": [
      {
        "product_name": "Футболка с принтом",
        "quantity": 2,
        "price": 150000,
        "currency": "rub"
      }
    ],
    "total": 300000,
    "currency": "rub",
    "shipping_address": "Россия, Москва, ул. Пушкина, д. 10, кв. 5",
    "tracking_number": "RU123456789CN",
    "created_at": "2025-03-20T01:15:58.33246Z",
    "updated_at": "2025-03-20T01:15:58.33246Z"
  }
}

Физический заказ отправлен

Уведомление об отправке физического заказа

Payload

application/json

namestring · enumRequiredExample: physical_order_shippedPossible values:

created_atstring · date-timeRequired

Время создания события

sent_atstring · date-timeRequired

Время отправки события

Responses

200

Вебхук успешно обработан

No content

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "physical_order_shipped",
  "created_at": "2026-02-02T14:18:03.017Z",
  "sent_at": "2026-02-02T14:18:03.017Z",
  "payload": {
    "order_id": 12345,
    "status": "pending",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "products": [
      {
        "product_name": "Футболка с принтом",
        "quantity": 2,
        "price": 150000,
        "currency": "rub"
      }
    ],
    "total": 300000,
    "currency": "rub",
    "shipping_address": "Россия, Москва, ул. Пушкина, д. 10, кв. 5",
    "tracking_number": "RU123456789CN",
    "created_at": "2025-03-20T01:15:58.33246Z",
    "updated_at": "2025-03-20T01:15:58.33246Z"
  }
}

Физический заказ отменен

Уведомление об отмене физического заказа

Payload

application/json

namestring · enumRequiredExample: physical_order_canceledPossible values:

created_atstring · date-timeRequired

Время создания события

sent_atstring · date-timeRequired

Время отправки события

Responses

200

Вебхук успешно обработан

No content

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "physical_order_canceled",
  "created_at": "2026-02-02T14:18:03.017Z",
  "sent_at": "2026-02-02T14:18:03.017Z",
  "payload": {
    "order_id": 12345,
    "status": "pending",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "products": [
      {
        "product_name": "Футболка с принтом",
        "quantity": 2,
        "price": 150000,
        "currency": "rub"
      }
    ],
    "total": 300000,
    "currency": "rub",
    "shipping_address": "Россия, Москва, ул. Пушкина, д. 10, кв. 5",
    "tracking_number": "RU123456789CN",
    "created_at": "2025-03-20T01:15:58.33246Z",
    "updated_at": "2025-03-20T01:15:58.33246Z"
  }
}

Новый донат

Уведомление о новом донате

Payload

application/json

namestring · enumRequiredExample: new_donationPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "new_donation",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "donation_request_id": 123,
    "donation_name": "Поддержать мою работу",
    "message": "Спасибо за ваш контент!",
    "period": "once",
    "amount": 1000,
    "currency": "usd",
    "anonymously": false,
    "web_app_link": "https://t.me/tribute/app?startapp=d123",
    "user_id": 31326,
    "telegram_user_id": 12321321
  }
}

Регулярный донат

Уведомление о платеже по регулярному донату

Payload

application/json

namestring · enumRequiredExample: recurrent_donationPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "recurrent_donation",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "donation_request_id": 123,
    "donation_name": "Ежемесячная поддержка",
    "period": "monthly",
    "amount": 500,
    "currency": "eur",
    "anonymously": false,
    "web_app_link": "https://t.me/tribute/app?startapp=d456",
    "user_id": 31326,
    "telegram_user_id": 12321321
  }
}

Отмена доната

Уведомление об отмене регулярного доната

Payload

application/json

namestring · enumRequiredExample: cancelled_donationPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "cancelled_donation",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "donation_request_id": 123,
    "donation_name": "Ежемесячная поддержка",
    "period": "monthly",
    "amount": 500,
    "currency": "eur",
    "anonymously": false,
    "web_app_link": "https://t.me/tribute/app?startapp=d456",
    "user_id": 31326,
    "telegram_user_id": 12321321
  }
}

Покупка цифрового товара

Уведомление о покупке цифрового товара

Payload

application/json

namestring · enumRequiredExample: new_digital_productPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "new_digital_product",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "product_id": 456,
    "product_name": "VPN Доступ - 1 месяц",
    "amount": 500,
    "currency": "usd",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "purchase_id": 78901,
    "transaction_id": 234567,
    "purchase_created_at": "2025-03-20T01:15:58.33246Z"
  }
}

Цифровой товар возвращён

Уведомление о возврате цифрового товара. Этот вебхук срабатывает когда:

• Пользователь возвращает Stars через App Store, Google Play или банк
• Автор инициирует возврат через API

Важно: Используйте purchase_id для сопоставления возвратов с оригинальными покупками и отзыва доступа к цифровому контенту.

Payload

application/json

namestring · enumRequiredExample: digital_product_refundedPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "digital_product_refunded",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "product_id": 456,
    "product_name": "VPN Доступ - 1 месяц",
    "amount": 500,
    "currency": "usd",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "purchase_id": 78901,
    "transaction_id": 234567,
    "refund_reason": "telegram_refund",
    "refunded_at": "2025-03-20T02:30:00.33246Z"
  }
}