commet-webhooks（评论网络钩子）

Commet Webhooks

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

Quick Start

// 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:

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:

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",
});

Event Types

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

Payload Envelope

Every webhook delivers a JSON payload with this structure:

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

Headers

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