payment-kit 1.22.28 → 1.22.29

package/README.md

@@ -25,11 +25,20 @@ The decentralized Stripe for the Blocklet platform.
 - Copy the `BLOCKLET_DEV_APP_DID`
 - Transfer 2 TBA from your DID Wallet to the copied address
 
+### Configure Stripe
+
+Before using Stripe as a payment method, you need to configure the webhook secret:
+
+1. Set the `STRIPE_WEBHOOK_SECRET` environment variable in your Blocklet settings
+   - Add the environment variable `STRIPE_WEBHOOK_SECRET` with your Stripe webhook signing secret
+   - You can find this in your Stripe Dashboard > Developers > Webhooks > Signing Secret
+
 ### Debug Stripe
 
 1. Install and log in following the instructions at: https://stripe.com/docs/stripe-cli
 2. Start your local Payment Kit server and note its port
 3. Run `stripe listen --forward-to http://127.0.0.1:8188/api/integrations/stripe/webhook --log-level=debug --latest`
+4. Copy the webhook signing secret from the CLI output and set it as `STRIPE_WEBHOOK_SECRET` environment variable
 
 ### Test Stripe
 

package/api/src/libs/env.ts

@@ -19,6 +19,12 @@ export const vendorReturnScanCronTime: string = process.env.VENDOR_RETURN_SCAN_C
 export const vendorTimeoutMinutes: number = process.env.VENDOR_TIMEOUT_MINUTES
   ? +process.env.VENDOR_TIMEOUT_MINUTES
   : 10; // 默认 10 分钟超时
+export const webhookAlertWindowMinutes: number = process.env.WEBHOOK_ALERT_WINDOW_MINUTES
+  ? +process.env.WEBHOOK_ALERT_WINDOW_MINUTES
+  : 10; // webhook 连续失败告警时间窗口，默认 10 分钟
+export const webhookAlertMinFailures: number = process.env.WEBHOOK_ALERT_MIN_FAILURES
+  ? +process.env.WEBHOOK_ALERT_MIN_FAILURES
+  : 3; // webhook 触发告警的最小失败次数，默认 3 次
 
 export const shortUrlApiKey: string = process.env.SHORT_URL_API_KEY || '';
 export const shortUrlDomain: string = process.env.SHORT_URL_DOMAIN || 's.abtnet.io';

package/api/src/libs/notification/template/webhook-endpoint-failed.ts

@@ -0,0 +1,140 @@
+import { getUrl } from '@blocklet/sdk/lib/component';
+import { withQuery } from 'ufo';
+import { getConnectQueryParam, getOwnerDid } from '../../util';
+import { translate } from '../../../locales';
+import { WebhookEndpoint } from '../../../store/models';
+import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
+import { getUserLocale } from '../../../integrations/blocklet/notification';
+
+export interface WebhookEndpointFailedEmailTemplateOptions {
+  webhookEndpointId: string;
+  failedCount: number;
+}
+
+interface WebhookEndpointFailedEmailTemplateContext {
+  locale: string;
+  userDid: string;
+  webhookDescription: string;
+  failedCount: number;
+  webhookEndpointId: string;
+  viewWebhookLink: string;
+}
+
+// eslint-disable-next-line prettier/prettier
+export class WebhookEndpointFailedEmailTemplate implements BaseEmailTemplate<WebhookEndpointFailedEmailTemplateContext> {
+  options: WebhookEndpointFailedEmailTemplateOptions;
+
+  constructor(options: WebhookEndpointFailedEmailTemplateOptions) {
+    this.options = options;
+  }
+
+  async getContext(): Promise<WebhookEndpointFailedEmailTemplateContext> {
+    const { webhookEndpointId, failedCount } = this.options;
+
+    const webhookEndpoint = await WebhookEndpoint.findByPk(webhookEndpointId);
+    if (!webhookEndpoint) {
+      throw new Error(`WebhookEndpoint not found: ${webhookEndpointId}`);
+    }
+
+    const userDid = await getOwnerDid();
+    if (!userDid) {
+      throw new Error('get owner did failed');
+    }
+
+    const locale = await getUserLocale(userDid);
+
+    const viewWebhookLink = getUrl(
+      withQuery(`admin/developers/${webhookEndpointId}`, {
+        locale,
+        ...getConnectQueryParam({ userDid }),
+      })
+    );
+
+    return {
+      userDid,
+      locale,
+      webhookDescription: webhookEndpoint.description || '',
+      failedCount,
+      webhookEndpointId,
+      viewWebhookLink,
+    };
+  }
+
+  async getTemplate(): Promise<BaseEmailTemplateType> {
+    const { locale, webhookDescription, failedCount, webhookEndpointId, viewWebhookLink } = await this.getContext();
+
+    const template: BaseEmailTemplateType = {
+      title: translate('notification.webhookEndpointFailed.title', locale, {
+        failedCount,
+      }),
+      body: translate('notification.webhookEndpointFailed.body', locale, {
+        failedCount,
+      }),
+      attachments: [
+        {
+          type: 'section',
+          fields: [
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.common.webhookEndpointId', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: webhookEndpointId,
+              },
+            },
+            webhookDescription
+              ? {
+                  type: 'text',
+                  data: {
+                    type: 'plain',
+                    color: '#9397A1',
+                    text: translate('notification.common.description', locale),
+                  },
+                }
+              : null,
+            webhookDescription
+              ? {
+                  type: 'text',
+                  data: {
+                    type: 'plain',
+                    text: webhookDescription,
+                  },
+                }
+              : null,
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.common.failedCount', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: failedCount.toString(),
+              },
+            },
+          ].filter(Boolean),
+        },
+      ],
+      actions: [
+        {
+          name: translate('notification.common.viewWebhook', locale),
+          title: translate('notification.common.viewWebhook', locale),
+          link: viewWebhookLink,
+        },
+      ].filter(Boolean),
+    };
+
+    return template;
+  }
+}

package/api/src/locales/en.ts

@@ -53,6 +53,11 @@ export default flat({
       reloadCredits: 'Reload Credits',
       invoiceNumber: 'Invoice Number',
       payer: 'Payer',
+      webhookEndpointId: 'Webhook Endpoint ID',
+      webhookUrl: 'Webhook URL',
+      description: 'Description',
+      failedCount: 'Failed Count',
+      viewWebhook: 'View Webhook',
     },
 
     billingDiscrepancy: {
@@ -60,6 +65,11 @@ export default flat({
       body: 'A billing discrepancy has been detected for {productName}. Please review your billing details.',
     },
 
+    webhookEndpointFailed: {
+      title: 'Webhook endpoint alert: {webhookUrl}',
+      body: 'Your webhook endpoint has failed {failedCount} times consecutively. Please check the webhook details and ensure the endpoint is accessible and functioning correctly.',
+    },
+
     sendTo: 'Sent to',
     mintNFT: {
       title: '{collection} NFT minted',

package/api/src/locales/zh.ts

@@ -53,6 +53,11 @@ export default flat({
       manageCredit: '管理额度',
       invoiceNumber: '账单编号',
       payer: '付款方',
+      webhookEndpointId: 'Webhook 端点 ID',
+      webhookUrl: 'Webhook URL',
+      description: '描述',
+      failedCount: '失败次数',
+      viewWebhook: '查看 Webhook',
     },
 
     sendTo: '发送给',
@@ -71,6 +76,11 @@ export default flat({
       body: '检测到 {productName} 账单金额核算不一致，请留意。',
     },
 
+    webhookEndpointFailed: {
+      title: 'Webhook 端点警告: {webhookUrl}',
+      body: '您的 Webhook 端点已连续失败 {failedCount} 次，请查看详情并确保端点可正常访问和工作。',
+    },
+
     meteringSubscriptionDetection: {
       title: '[{appName}] 按量计费订阅检测',
       body: '在 {startTimeStr} - {endTimeStr} 期间，共扫描了 {totalCount} 份按量计费的订阅，其中 {normalCount} 份为正常订阅，{abnormalCount} 份存在异常，包括 {unreportedCount} 份未上报的订阅和 {discrepantCount} 份账单核算有问题的订阅。\n\n 异常订阅:',

package/api/src/queues/notification.ts

@@ -110,6 +110,10 @@ import {
   AggregatedSubscriptionRenewedEmailTemplate,
   AggregatedSubscriptionRenewedEmailTemplateOptions,
 } from '../libs/notification/template/aggregated-subscription-renewed';
+import {
+  WebhookEndpointFailedEmailTemplate,
+  WebhookEndpointFailedEmailTemplateOptions,
+} from '../libs/notification/template/webhook-endpoint-failed';
 import type { TJob } from '../store/models/job';
 
 export type NotificationQueueJobOptions = any;
@@ -134,7 +138,8 @@ export type NotificationQueueJobType =
   | 'customer.credit.insufficient'
   | 'customer.credit_grant.granted'
   | 'customer.credit.low_balance'
-  | 'customer.auto_recharge.failed';
+  | 'customer.auto_recharge.failed'
+  | 'webhook.endpoint.failed';
 
 export type NotificationQueueJob = {
   type: NotificationQueueJobType;
@@ -280,6 +285,10 @@ async function getNotificationTemplate(job: NotificationQueueJob): Promise<BaseE
     return new CustomerAutoRechargeFailedEmailTemplate(job.options as CustomerAutoRechargeFailedEmailTemplateOptions);
   }
 
+  if (job.type === 'webhook.endpoint.failed') {
+    return new WebhookEndpointFailedEmailTemplate(job.options as WebhookEndpointFailedEmailTemplateOptions);
+  }
+
   throw new Error(`Unknown job type: ${job.type}`);
 }
 

package/api/src/queues/webhook.ts

@@ -1,15 +1,18 @@
-import { sign } from '@blocklet/sdk/lib/util/verify-sign';
-import axios, { AxiosError } from 'axios';
+import componentApi from '@blocklet/sdk/lib/util/component-api';
+import { AxiosError } from 'axios';
+import { Op } from 'sequelize';
 
 import { wallet } from '../libs/auth';
 import logger from '../libs/logger';
 import createQueue from '../libs/queue';
 import { MAX_RETRY_COUNT, getNextRetry, getWebhookJobId } from '../libs/util';
+import { webhookAlertWindowMinutes, webhookAlertMinFailures } from '../libs/env';
 import { Customer } from '../store/models/customer';
 import { Event } from '../store/models/event';
 import { PaymentCurrency } from '../store/models/payment-currency';
 import { WebhookAttempt } from '../store/models/webhook-attempt';
 import { WebhookEndpoint } from '../store/models/webhook-endpoint';
+import { addNotificationJob } from './notification';
 
 type WebhookJob = {
   eventId: string;
@@ -55,7 +58,7 @@ export const handleWebhook = async (job: WebhookJob) => {
     }
 
     // verify similar to component call, but supports external urls
-    const result = await axios({
+    const result = await componentApi.request({
       url: webhook.url,
       method: 'POST',
       timeout: 60 * 1000,
@@ -63,8 +66,6 @@ export const handleWebhook = async (job: WebhookJob) => {
       headers: {
         'x-app-id': wallet.address,
         'x-app-pk': wallet.publicKey,
-        'x-component-sig': await sign(json),
-        'x-component-did': process.env.BLOCKLET_COMPONENT_DID as string,
       },
     });
 
@@ -85,18 +86,28 @@ export const handleWebhook = async (job: WebhookJob) => {
     logger.info('webhook attempt success', { ...job, retryCount });
   } catch (err: any) {
     logger.warn('webhook attempt error', { ...job, retryCount, message: err.message });
+    const errorStatus = (err as AxiosError).response?.status || 500;
+
     await WebhookAttempt.create({
       livemode: event.livemode,
       event_id: event.id,
       webhook_endpoint_id: webhook.id,
       status: 'failed',
-      response_status: (err as AxiosError).response?.status || 500,
+      response_status: errorStatus,
       response_body: (err as AxiosError).response?.data || {},
       retry_count: retryCount,
     });
     logger.info('Failed WebhookAttempt created', { eventId: event.id, webhookId: webhook.id });
 
-    // reschedule next attempt
+    try {
+      await checkAndNotifyWebhookFailures(webhook.id);
+    } catch (notifyError: any) {
+      logger.error('Failed to check and notify webhook failures', {
+        webhookId: webhook.id,
+        error: notifyError.message,
+      });
+    }
+
     if (retryCount < MAX_RETRY_COUNT) {
       process.nextTick(() => {
         webhookQueue.push({
@@ -117,6 +128,48 @@ export const handleWebhook = async (job: WebhookJob) => {
   }
 };
 
+// Alert if webhook continuously fails within configured time window
+async function checkAndNotifyWebhookFailures(webhookId: string) {
+  const alertWindowStart = new Date(Date.now() - webhookAlertWindowMinutes * 60 * 1000);
+
+  const recentAttempts = await WebhookAttempt.findAll({
+    where: {
+      webhook_endpoint_id: webhookId,
+      created_at: { [Op.gte]: alertWindowStart },
+    },
+    order: [['created_at', 'DESC']],
+    attributes: ['status'],
+  });
+
+  const hasSuccessInWindow = recentAttempts.some((attempt) => attempt.status === 'succeeded');
+  if (hasSuccessInWindow) {
+    return;
+  }
+
+  const failedCountInWindow = recentAttempts.filter((attempt) => attempt.status === 'failed').length;
+  if (failedCountInWindow < webhookAlertMinFailures) {
+    return;
+  }
+
+  addNotificationJob(
+    'webhook.endpoint.failed',
+    {
+      webhookEndpointId: webhookId,
+      failedCount: failedCountInWindow,
+    },
+    [webhookId],
+    true,
+    24 * 3600
+  );
+
+  logger.info('Notification job added for webhook consecutive failures', {
+    webhookId,
+    failedCountInWindow,
+    alertWindowMinutes: webhookAlertWindowMinutes,
+    minFailures: webhookAlertMinFailures,
+  });
+}
+
 export const webhookQueue = createQueue<WebhookJob>({
   name: 'webhook',
   onJob: handleWebhook,

package/blocklet.yml

@@ -14,7 +14,7 @@ repository:
   type: git
   url: git+https://github.com/blocklet/payment-kit.git
 specVersion: 1.2.8
-version: 1.22.28
+version: 1.22.29
 logo: logo.png
 files:
   - dist
@@ -79,6 +79,12 @@ environments:
     default: s.abtnet.io
     secure: false
     shared: false
+  - name: STRIPE_WEBHOOK_SECRET
+    description: Stripe webhook secret
+    required: false
+    default: ''
+    secure: true
+    shared: false
 capabilities:
   navigation: true
   clusterMode: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.22.28",
+  "version": "1.22.29",
   "scripts": {
     "dev": "blocklet dev --open",
     "lint": "tsc --noEmit && eslint src api/src --ext .mjs,.js,.jsx,.ts,.tsx",
@@ -44,23 +44,23 @@
     ]
   },
   "dependencies": {
-    "@abtnode/cron": "^1.17.3",
-    "@arcblock/did": "^1.27.12",
+    "@abtnode/cron": "^1.17.4-beta-20251204-152224-243ff54f",
+    "@arcblock/did": "^1.27.13",
     "@arcblock/did-connect-react": "^3.2.11",
     "@arcblock/did-connect-storage-nedb": "^1.8.0",
-    "@arcblock/did-util": "^1.27.12",
-    "@arcblock/jwt": "^1.27.12",
+    "@arcblock/did-util": "^1.27.13",
+    "@arcblock/jwt": "^1.27.13",
     "@arcblock/react-hooks": "^3.2.11",
     "@arcblock/ux": "^3.2.11",
-    "@arcblock/validator": "^1.27.12",
-    "@blocklet/did-space-js": "^1.2.7",
-    "@blocklet/error": "^0.3.3",
-    "@blocklet/js-sdk": "^1.17.3",
-    "@blocklet/logger": "^1.17.3",
-    "@blocklet/payment-broker-client": "1.22.28",
-    "@blocklet/payment-react": "1.22.28",
-    "@blocklet/payment-vendor": "1.22.28",
-    "@blocklet/sdk": "^1.17.3",
+    "@arcblock/validator": "^1.27.13",
+    "@blocklet/did-space-js": "^1.2.8",
+    "@blocklet/error": "^0.3.4",
+    "@blocklet/js-sdk": "^1.17.4-beta-20251204-152224-243ff54f",
+    "@blocklet/logger": "^1.17.4-beta-20251204-152224-243ff54f",
+    "@blocklet/payment-broker-client": "1.22.29",
+    "@blocklet/payment-react": "1.22.29",
+    "@blocklet/payment-vendor": "1.22.29",
+    "@blocklet/sdk": "^1.17.4-beta-20251204-152224-243ff54f",
     "@blocklet/ui-react": "^3.2.11",
     "@blocklet/uploader": "^0.3.13",
     "@blocklet/xss": "^0.3.11",
@@ -68,11 +68,11 @@
     "@mui/lab": "7.0.0-beta.14",
     "@mui/material": "^7.1.2",
     "@mui/system": "^7.1.1",
-    "@ocap/asset": "^1.27.12",
-    "@ocap/client": "^1.27.12",
-    "@ocap/mcrypto": "^1.27.12",
-    "@ocap/util": "^1.27.12",
-    "@ocap/wallet": "^1.27.12",
+    "@ocap/asset": "^1.27.13",
+    "@ocap/client": "^1.27.13",
+    "@ocap/mcrypto": "^1.27.13",
+    "@ocap/util": "^1.27.13",
+    "@ocap/wallet": "^1.27.13",
     "@stripe/react-stripe-js": "^2.9.0",
     "@stripe/stripe-js": "^2.4.0",
     "ahooks": "^3.8.5",
@@ -127,9 +127,9 @@
     "web3": "^4.16.0"
   },
   "devDependencies": {
-    "@abtnode/types": "^1.17.3",
+    "@abtnode/types": "^1.17.4-beta-20251204-152224-243ff54f",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.22.28",
+    "@blocklet/payment-types": "1.22.29",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -160,7 +160,7 @@
     "vite": "^7.0.0",
     "vite-node": "^3.2.4",
     "vite-plugin-babel-import": "^2.0.5",
-    "vite-plugin-blocklet": "^0.12.3",
+    "vite-plugin-blocklet": "^0.12.4",
     "vite-plugin-node-polyfills": "^0.23.0",
     "vite-plugin-svgr": "^4.3.0",
     "vite-tsconfig-paths": "^5.1.4",
@@ -176,5 +176,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "b3c8797e5ffe68ae3a0de1962b1d076a9d2fef33"
+  "gitHead": "8438b592c3709dc2ae5aeceb0cd883277de3d646"
 }

package/src/locales/en.tsx

@@ -1119,6 +1119,9 @@ export default flat({
           label: 'Webhook Signing Secret',
           tip: 'Webhook Signing Secret, See Dashboard > Developers > Webhooks > Signing Secret',
         },
+        webhookHint:
+          'If webhook events are not received, manually configure STRIPE_WEBHOOK_SECRET in environment variables',
+        configureEnv: 'Go to Settings',
       },
       arcblock: {
         chain_id: {

package/src/locales/zh.tsx

@@ -1074,6 +1074,8 @@ export default flat({
           label: '钩子签名密钥',
           tip: '钩子签名密钥，请查看仪表板 > 开发人员 > 钩子 > 签名密钥',
         },
+        webhookHint: '若无法接收 Webhook 事件，可手动在环境变量配置 STRIPE_WEBHOOK_SECRET',
+        configureEnv: '前往配置',
       },
       arcblock: {
         chain_id: {

package/src/pages/admin/developers/index.tsx

@@ -10,16 +10,14 @@ const EventDetail = React.lazy(() => import('./events/detail'));
 const WebhookDetail = React.lazy(() => import('./webhooks/detail'));
 
 const pages = {
-  overview: React.lazy(() => import('./overview')),
   webhooks: React.lazy(() => import('./webhooks')),
   events: React.lazy(() => import('./events')),
-  logs: React.lazy(() => import('./logs')),
 };
 
 export default function DevelopersIndex() {
   const navigate = useNavigate();
   const { t } = useLocaleContext();
-  const { page = 'overview' } = useParams();
+  const { page = 'webhooks' } = useParams();
   const { startTransition } = useTransitionContext();
 
   if (page.startsWith('evt_')) {
@@ -37,12 +35,10 @@ export default function DevelopersIndex() {
   };
 
   // @ts-ignore
-  const TabComponent = pages[page] || pages.overview;
+  const TabComponent = pages[page] || pages.webhooks;
   const tabs = [
-    { label: t('admin.overview'), value: 'overview' },
     { label: t('admin.webhooks'), value: 'webhooks' },
     { label: t('admin.events.title'), value: 'events' },
-    { label: t('admin.logs'), value: 'logs' },
   ];
 
   return (

package/src/pages/admin/settings/payment-methods/index.tsx

@@ -498,7 +498,51 @@ export default function PaymentMethods() {
                     />
                   )}
 
-                  <InfoRow label={t('admin.paymentMethod.props.confirmation')} value={method.confirmation.type} />
+                  <InfoRow
+                    label={t('admin.paymentMethod.props.confirmation')}
+                    value={
+                      <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+                        <Typography variant="body2">{method.confirmation.type}</Typography>
+                        {method.type === 'stripe' && method.confirmation.type === 'callback' && (
+                          <Tooltip
+                            title={
+                              <Typography variant="body2" component="span">
+                                {t('admin.paymentMethod.stripe.webhookHint')}{' '}
+                                <Typography
+                                  variant="body2"
+                                  component="a"
+                                  href="/.well-known/service/admin/overview/components"
+                                  target="_blank"
+                                  rel="noopener noreferrer"
+                                  sx={{
+                                    color: 'primary.light',
+                                    textDecoration: 'underline',
+                                    '&:hover': {
+                                      color: 'primary.main',
+                                    },
+                                  }}>
+                                  {t('admin.paymentMethod.stripe.configureEnv')}
+                                </Typography>
+                              </Typography>
+                            }
+                            placement="right"
+                            arrow>
+                            <InfoOutlined
+                              sx={{
+                                fontSize: 16,
+                                color: 'info.main',
+                                cursor: 'help',
+                                transition: 'color 0.2s',
+                                '&:hover': {
+                                  color: 'info.dark',
+                                },
+                              }}
+                            />
+                          </Tooltip>
+                        )}
+                      </Box>
+                    }
+                  />
                   <InfoRow
                     label={t('admin.paymentMethod.props.recurring')}
                     value={method.features.recurring ? t('common.yes') : t('common.no')}