Webhooks

Webhooks for system event notifications.

Setup:

1. Go to Creator Dashboard → Settings (three-dot menu) → API Keys section

2. Generate API key if you haven't already

3. Specify your webhook URL in the webhook settings

Signature verification: Each request contains trbt-signature header with HMAC-SHA256 signature of request body signed with your API key.

Retry attempts: On delivery failure, system retries with exponential backoff over ~24 hours: 5min, 15min, 30min, 1h, 2h, 4h, 8h, 8h.

Subscription type (payload.type) in subscription events:

• regular — regular paid subscription (new subscription or renewal)

• gift — gift subscription (gift purchase)

• trial — trial subscription (trial activation)

Type transitions: When a gift or trial subscription renews, the next subscription becomes regular, reflected in the renewed_subscription event.

New Subscription

Notification about user purchasing a subscription

Payload

application/json

namestring · enumRequiredExample: new_subscriptionPossible values:

created_atstring · date-timeRequired

Event creation time

Example: 2025-08-25T01:15:58.33246Z

sent_atstring · date-timeRequired

Event sending time

Example: 2025-08-25T01:15:58.542279448Z

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "name": "new_subscription",
  "created_at": "2025-08-25T01:15:58.33246Z",
  "sent_at": "2025-08-25T01:15:58.542279448Z",
  "payload": {
    "subscription_name": "Support creativity 🌟",
    "subscription_id": 1644,
    "period_id": 1547,
    "period": "monthly",
    "type": "regular",
    "price": 1000,
    "amount": 700,
    "currency": "eur",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "channel_id": 614,
    "channel_name": "lbs",
    "expires_at": "2025-04-20T01:15:57.305733Z"
  }
}

Cancelled Subscription

Notification about user cancelling a subscription

Payload

application/json

namestring · enumRequiredExample: cancelled_subscriptionPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "name": "cancelled_subscription",
  "created_at": "2025-03-21T11:20:44.013969Z",
  "sent_at": "2025-03-21T11:20:44.527657077Z",
  "payload": {
    "subscription_name": "Join the private club 🎉",
    "subscription_id": 1646,
    "period_id": 1549,
    "period": "monthly",
    "type": "regular",
    "price": 1000,
    "amount": 1000,
    "currency": "eur",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "channel_id": 614,
    "channel_name": "lbs",
    "cancel_reason": "",
    "expires_at": "2025-03-20T11:13:44.737Z"
  }
}

Renewed Subscription

Notification about subscription renewal

Payload

application/json

created_atstring · date-timeRequired

Event creation time

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

namestring · enumRequiredExample: renewed_subscriptionPossible values:

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "created_at": "2025-03-21T11:20:44.013969Z",
  "name": "renewed_subscription",
  "payload": {
    "subscription_name": "Support creativity 🌟",
    "subscription_id": 1644,
    "period_id": 1547,
    "period": "monthly",
    "price": 1000,
    "amount": 700,
    "currency": "eur",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "email": "[e-mail]",
    "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"
}

Physical Order Created

Notification about new physical order creation

Payload

application/json

namestring · enumRequiredExample: physical_order_createdPossible values:

created_atstring · date-timeRequired

Event creation time

sent_atstring · date-timeRequired

Event sending time

Responses

200

Webhook successfully processed

No content

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "name": "physical_order_created",
  "created_at": "2026-08-07T14:46:13.673Z",
  "sent_at": "2026-08-07T14:46:13.673Z",
  "payload": {
    "order_id": 12345,
    "status": "pending",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "products": [
      {
        "product_name": "T-shirt with print",
        "quantity": 2,
        "price": 150000,
        "currency": "usd"
      }
    ],
    "total": 300000,
    "currency": "usd",
    "shipping_address": "USA, New York, 5th Avenue, 123, Apt 45",
    "tracking_number": "US123456789CN",
    "created_at": "2025-03-20T01:15:58.33246Z",
    "updated_at": "2025-03-20T01:15:58.33246Z"
  }
}

Physical Order Shipped

Notification about physical order shipping

Payload

application/json

namestring · enumRequiredExample: physical_order_shippedPossible values:

created_atstring · date-timeRequired

Event creation time

sent_atstring · date-timeRequired

Event sending time

Responses

200

Webhook successfully processed

No content

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "name": "physical_order_shipped",
  "created_at": "2026-08-07T14:46:13.673Z",
  "sent_at": "2026-08-07T14:46:13.673Z",
  "payload": {
    "order_id": 12345,
    "status": "pending",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "products": [
      {
        "product_name": "T-shirt with print",
        "quantity": 2,
        "price": 150000,
        "currency": "usd"
      }
    ],
    "total": 300000,
    "currency": "usd",
    "shipping_address": "USA, New York, 5th Avenue, 123, Apt 45",
    "tracking_number": "US123456789CN",
    "created_at": "2025-03-20T01:15:58.33246Z",
    "updated_at": "2025-03-20T01:15:58.33246Z"
  }
}

Physical Order Canceled

Notification about physical order cancellation

Payload

application/json

namestring · enumRequiredExample: physical_order_canceledPossible values:

created_atstring · date-timeRequired

Event creation time

sent_atstring · date-timeRequired

Event sending time

Responses

200

Webhook successfully processed

No content

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "name": "physical_order_canceled",
  "created_at": "2026-08-07T14:46:13.673Z",
  "sent_at": "2026-08-07T14:46:13.673Z",
  "payload": {
    "order_id": 12345,
    "status": "pending",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "products": [
      {
        "product_name": "T-shirt with print",
        "quantity": 2,
        "price": 150000,
        "currency": "usd"
      }
    ],
    "total": 300000,
    "currency": "usd",
    "shipping_address": "USA, New York, 5th Avenue, 123, Apt 45",
    "tracking_number": "US123456789CN",
    "created_at": "2025-03-20T01:15:58.33246Z",
    "updated_at": "2025-03-20T01:15:58.33246Z"
  }
}

New Donation

Notification about a new donation

Payload

application/json

namestring · enumRequiredExample: new_donationPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

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": "Support my work",
    "message": "Thank you for your content!",
    "period": "once",
    "amount": 1000,
    "currency": "usd",
    "anonymously": false,
    "web_app_link": "https://t.me/tribute/app?startapp=d123",
    "email": "[e-mail]",
    "trb_user_id": "W-15408",
    "telegram_user_id": 12321321,
    "telegram_username": "durov"
  }
}

Recurrent Donation

Notification about a recurring donation payment

Payload

application/json

namestring · enumRequiredExample: recurrent_donationPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

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": "Monthly support",
    "period": "monthly",
    "amount": 500,
    "currency": "eur",
    "anonymously": false,
    "web_app_link": "https://t.me/tribute/app?startapp=d456",
    "trb_user_id": "W-15408",
    "telegram_user_id": 12321321,
    "telegram_username": "durov"
  }
}

Cancelled Donation

Notification about a cancelled recurring donation

Payload

application/json

namestring · enumRequiredExample: cancelled_donationPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

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": "Monthly support",
    "period": "monthly",
    "amount": 500,
    "currency": "eur",
    "anonymously": false,
    "web_app_link": "https://t.me/tribute/app?startapp=d456",
    "trb_user_id": "W-15408",
    "telegram_user_id": 12321321,
    "telegram_username": "durov"
  }
}

New Digital Product Purchase

Notification about a digital product purchase

Payload

application/json

namestring · enumRequiredExample: new_digital_productPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

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 Access - 1 Month",
    "amount": 500,
    "currency": "usd",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "purchase_id": 78901,
    "transaction_id": 234567,
    "purchase_created_at": "2025-03-20T01:15:58.33246Z"
  }
}

Digital Product Refunded

Notification about a digital product refund. This webhook is triggered when:

• A user refunds Stars through App Store, Google Play, or their bank
• A creator initiates a refund via the API

Important: Use purchase_id to match refunds with original purchases and revoke access to digital content.

Payload

application/json

namestring · enumRequiredExample: digital_product_refundedPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

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 Access - 1 Month",
    "amount": 500,
    "currency": "usd",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "purchase_id": 78901,
    "transaction_id": 234567,
    "refund_reason": "telegram_refund",
    "refunded_at": "2025-03-20T02:30:00.33246Z"
  }
}