Webhooks

Webhook notifications for shop events.

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.

Shop Order

Notification about a shop order payment completion.

Payload

application/json

namestring · enumRequiredExample: shop_orderPossible 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": "shop_order",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "fee": 8000,
    "status": "paid",
    "email": "[email protected]",
    "customerId": "user_12345",
    "isRecurrent": false,
    "period": "monthly",
    "paymentToken": "660e8400-e29b-41d4-a716-446655440001",
    "cardLast4": "4242",
    "cardBrand": "VISA",
    "starsAmount": 0,
    "onlyStars": false,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Shop Order Charge Failed

Notification when a recurring shop order charge fails. Sent after each failed charge attempt. The system makes up to 3 attempts (1 initial + 2 retries) over ~8 hours before cancelling the subscription.

Only fires for card-based recurring payments. Subscriptions paid directly with Telegram Stars (no fiat card on file) are auto-renewed by Telegram itself — when Telegram does not renew, the subscription is cancelled with cancelReason="stars_subscription_expired" via shop_order_cancelled without any preceding shop_order_charge_failed events.

Charge timing relative to memberExpiresAt:

• Card payments: charge happens strictly after memberExpiresAt, typically within minutes.
• OnlyStars (card-to-Stars): charge happens up to 72 hours before memberExpiresAt to pre-purchase Stars for Telegram renewal.

Payload

application/json

namestring · enumRequiredExample: shop_order_charge_failedPossible 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": "shop_order_charge_failed",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "chargeRetries": 1,
    "email": "[email protected]",
    "customerId": "user_12345",
    "isRecurrent": true,
    "starsAmount": 0,
    "onlyStars": false,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Shop Order Charge Success

Notification when a recurring shop order is charged successfully.

Payload

application/json

namestring · enumRequiredExample: shop_order_charge_successPossible 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": "shop_order_charge_success",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "email": "[email protected]",
    "customerId": "user_12345",
    "isRecurrent": true,
    "starsAmount": 0,
    "onlyStars": false,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Shop Order Cancelled

Notification when a recurring shop order subscription is cancelled. See cancelReason in the payload for the trigger:

• cancelled_by_seller — explicit cancel from the Mini App / public API (POST /api/v1/shop/orders/{orderUuid}/cancel).
• charge_failed — recurring charge could not be completed after all retries.
• payment_method_expired — saved card is no longer usable.
• stars_subscription_expired — Telegram Stars subscription did not auto-renew (no fiat card on file; renewal is handled by Telegram).
• seller_unavailable — seller can no longer accept payments.
• last_charge_refunded — the buyer's most recently created shop-order buyer transaction was refunded (via any path: bank chargeback, Telegram Stars refund, manual seller refund). Refunding an older charge while a newer one still exists does NOT cancel the subscription. This event is emitted in addition to the shop_order_refunded event for the same transaction.

Payload

application/json

namestring · enumRequiredExample: shop_order_cancelledPossible 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": "shop_order_cancelled",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "cancelReason": "cancelled_by_seller",
    "email": "[email protected]",
    "customerId": "user_12345",
    "isRecurrent": true,
    "starsAmount": 0,
    "onlyStars": false,
    "memberStatus": "cancelled",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Shop Token Charge Success

Notification when a merchant-initiated token charge completes successfully.

Payload

application/json

namestring · enumRequiredExample: shop_token_charge_successPossible 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": "shop_token_charge_success",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "chargeUuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "token": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 100000,
    "currency": "rub",
    "reference": "order-123",
    "processedAt": "2025-03-20T01:16:02Z"
  }
}

Shop Token Charge Failed

Notification when a merchant-initiated token charge fails.

Payload

application/json

namestring · enumRequiredExample: shop_token_charge_failedPossible 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": "shop_token_charge_failed",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "chargeUuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "token": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 100000,
    "currency": "rub",
    "reference": "order-123",
    "errorCode": "payment_declined",
    "errorMessage": "Card was declined by the issuer"
  }
}

Shop Order Refunded

Notification when a shop order transaction is refunded. Fires for one-time and recurring orders alike, regardless of refund trigger (bank chargeback, Telegram Stars refund, manual seller refund).

Lifecycle. Manual seller-initiated refunds emit status=initiated first, then a second event with status=completed once the provider confirms. Bank chargebacks and Telegram Stars refunds skip the initiated step and emit status=completed directly. Consumers must idempotently handle two events with the same transactionId (one per status).

Recurring orders — last-charge cancellation. When the refunded transactionId is the most recently created shop-order buyer transaction for a recurring subscription, this event is followed by a shop_order_cancelled event with cancelReason="last_charge_refunded". Refunding an older charge (i.e., when a newer recurring charge still exists for the same subscription) does NOT cancel the member.

Payload

application/json

namestring · enumRequiredExample: shop_order_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": "shop_order_refunded",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "transactionId": 12345,
    "amount": 100000,
    "currency": "rub",
    "status": "initiated",
    "refundedAt": "2025-03-20T01:15:58.33246Z",
    "customerId": "user_12345",
    "isRecurrent": false,
    "period": "onetime",
    "starsAmount": 0,
    "onlyStars": false,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Shop Order Payment Failed

Notification when an initial shop order payment fails (e.g., card declined, insufficient funds). This is sent for one-time payments that fail during the initial payment attempt.

Payload

application/json

namestring · enumRequiredExample: shop_order_payment_failedPossible 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": "shop_order_payment_failed",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "errorCode": "payment_declined",
    "errorMessage": "Card declined by issuer",
    "email": "[email protected]",
    "customerId": "user_12345",
    "starsAmount": 0,
    "onlyStars": false
  }
}

Customer paid the invoice

The customer has paid the invoice. Sent immediately after payment, before the shop_order webhook.

This is an intermediate signal: funds have not been credited to the merchant yet and the payment may not complete. Do not deliver goods or treat the order as paid — the final status arrives via the shop_order webhook.

Payload

application/json

namestring · enumRequiredExample: shop_order_payment_receivedPossible 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": "shop_order_payment_received",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "starsAmount": 150,
    "onlyStars": true,
    "starsPurchaseId": 4711,
    "email": "[email protected]",
    "customerId": "user_12345"
  }
}