commet-webhooks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Commet Webhooks

Receive real-time HTTP notifications when billing events happen in Commet -- subscriptions activating, payments failing, invoices being created, and more.

当Commet中发生账单事件时接收实时HTTP通知——包括订阅激活、支付失败、发票生成等各类场景。

Quick Start

快速开始

typescript

// app/api/webhooks/commet/route.ts
import { Webhooks } from "@commet/next";

export const POST = Webhooks({
  webhookSecret: process.env.COMMET_WEBHOOK_SECRET!,

  onSubscriptionActivated: async (payload) => {
    await sendWelcomeEmail(payload.data.externalId);
  },

  onSubscriptionCanceled: async (payload) => {
    await sendCancellationEmail(payload.data.externalId);
  },
});

Install the handler package:

bash

npm install @commet/next

typescript

// app/api/webhooks/commet/route.ts
import { Webhooks } from "@commet/next";

export const POST = Webhooks({
  webhookSecret: process.env.COMMET_WEBHOOK_SECRET!,

  onSubscriptionActivated: async (payload) => {
    await sendWelcomeEmail(payload.data.externalId);
  },

  onSubscriptionCanceled: async (payload) => {
    await sendCancellationEmail(payload.data.externalId);
  },
});

安装处理程序包：

bash

npm install @commet/next

Key Gotcha: Query State Directly

重要注意事项：直接查询状态

Webhooks are for background tasks (sending emails, provisioning resources, logging). They should never be the source of truth for access control or subscription state.

Always query the SDK directly when you need to check a customer's status:

typescript

import { Commet } from "@commet/node";

const commet = new Commet({ apiKey: process.env.COMMET_API_KEY! });

// Check subscription status -- do this, not webhook state sync
const { data: sub } = await commet.subscriptions.get("user_123");
if (sub?.status === "active" || sub?.status === "trialing") {
  // grant access
}

// Check feature access
const { data } = await commet.features.check({
  code: "advanced_analytics",
  customerId: "user_123",
});

Webhooks适用于后台任务（发送邮件、资源调配、日志记录），切勿将其作为访问控制或订阅状态的可信数据源。

当你需要查询客户状态时，请始终直接调用SDK：

typescript

import { Commet } from "@commet/node";

const commet = new Commet({ apiKey: process.env.COMMET_API_KEY! });

// 检查订阅状态 -- 请使用该方式，不要同步webhook状态
const { data: sub } = await commet.subscriptions.get("user_123");
if (sub?.status === "active" || sub?.status === "trialing") {
  // 授予访问权限
}

// 检查功能访问权限
const { data } = await commet.features.check({
  code: "advanced_analytics",
  customerId: "user_123",
});

Event Types

事件类型

Event	When Fired	Common Use
`subscription.created`	New subscription created, before payment	Logging, analytics
`subscription.activated`	Payment successful, subscription active	Welcome email, provision resources
`subscription.canceled`	Subscription canceled	Cancellation email, schedule cleanup
`subscription.updated`	Subscription details changed	Sync external systems
`subscription.plan_changed`	Plan upgrade/downgrade	Notify of plan change, adjust resources
`payment.received`	Recurring payment processed	Receipt email, update accounting
`payment.failed`	Recurring charge failed	Alert customer, dunning flow
`invoice.created`	New invoice generated	Custom invoice handling

See references/events.md for full payload shapes and examples.

事件	触发时机	常见用途
`subscription.created`	新订阅已创建，尚未完成支付	日志记录、数据分析
`subscription.activated`	支付成功，订阅生效	发送欢迎邮件、资源调配
`subscription.canceled`	订阅已取消	发送取消通知邮件、安排资源清理
`subscription.updated`	订阅详情变更	同步外部系统
`subscription.plan_changed`	套餐升级/降级	通知套餐变更、调整资源
`payment.received`	定期支付处理完成	发送收据邮件、更新财务账目
`payment.failed`	定期扣费失败	提醒客户、催缴流程
`invoice.created`	新发票已生成	自定义发票处理

完整的payload结构和示例请查看 references/events.md。

Payload Envelope

负载结构

Every webhook delivers a JSON payload with this structure:

json

{
  "event": "subscription.activated",
  "timestamp": "2026-03-25T14:30:00.000Z",
  "organizationId": "org_abc123",
  "data": { }
}

每个webhook推送的JSON payload都遵循以下结构：

json

{
  "event": "subscription.activated",
  "timestamp": "2026-03-25T14:30:00.000Z",
  "organizationId": "org_abc123",
  "data": { }
}

Headers

请求头

Header	Description
`X-Commet-Signature`	HMAC-SHA256 hex signature of the raw body
`X-Commet-Event`	The event type
`X-Commet-Timestamp`	ISO 8601 datetime when the event was emitted

请求头	描述
`X-Commet-Signature`	原始请求体的HMAC-SHA256十六进制签名
`X-Commet-Event`	事件类型
`X-Commet-Timestamp`	事件触发的ISO 8601格式时间

When to Load References

参考文档指引

Setting up webhooks or verifying signatures -> references/setup.md
Event payload shapes and fields -> references/events.md
Next.js, Express, or Better Auth handlers -> references/framework-handlers.md

设置webhook或验证签名 -> references/setup.md
事件payload结构和字段说明 -> references/events.md
Next.js、Express或Better Auth处理程序 -> references/framework-handlers.md