> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# مكون Convex

> تعلم كيفية دمج مدفوعات Dodo مع خلفية Convex الخاصة بك باستخدام مكون Convex. يغطي وظائف الدفع، بوابة العملاء، الويب هوكس، وإعداد البيئة الآمنة.

<CardGroup cols={2}>
  <Card title="Checkout Function" icon="cart-shopping" href="#checkout-function">
    دمج عملية إنهاء الدفع الخاصة بـ Dodo Payments مع تدفق قائم على الجلسة.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-function">
    السماح للعملاء بإدارة الاشتراكات والتفاصيل.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-handler">
    استلام أحداث الويب هوك من Dodo Payments ومعالجتها.
  </Card>
</CardGroup>

## التثبيت

<Steps>
  <Step title="Install the package">
    قم بتشغيل الأمر التالي في جذر مشروعك:

    ```bash theme={null}
    npm install @dodopayments/convex
    ```
  </Step>

  <Step title="Add Component to Convex Config">
    أضف مكون Dodo Payments إلى تكوين Convex الخاص بك:

    ```typescript theme={null}
    // convex/convex.config.ts
    import { defineApp } from "convex/server";
    import dodopayments from "@dodopayments/convex/convex.config";

    const app = defineApp();
    app.use(dodopayments);
    export default app;
    ```

    بعد تعديل `convex.config.ts`، شغّل `npx convex dev` مرة واحدة لتوليد الأنواع اللازمة.
  </Step>

  <Step title="Set up environment variables">
    قم بإعداد متغيرات البيئة في لوحة تحكم Convex (**Settings** → **Environment Variables**). يمكنك الوصول إلى اللوحة عن طريق تشغيل:

    ```bash theme={null}
    npx convex dashboard
    ```

    أضف متغيرات البيئة التالية:

    * `DODO_PAYMENTS_API_KEY` - مفتاح واجهة برمجة تطبيقات Dodo Payments الخاص بك
    * `DODO_PAYMENTS_ENVIRONMENT` - اضبطه على `test_mode` أو `live_mode`
    * `DODO_PAYMENTS_WEBHOOK_SECRET` - سر الويب هوك الخاص بك (مطلوب لمعالجة الويب هوك)

    <Warning>
      استخدم دائمًا متغيرات بيئة Convex للمعلومات الحساسة. لا تقم أبدًا بتسجيل الأسرار في نظام التحكم في الإصدار.
    </Warning>
  </Step>
</Steps>

## أمثلة إعداد المكون

<Steps>
  <Step title="Create Internal Query">
    أولًا، أنشئ استعلامًا داخليًا لجلب العملاء من قاعدة بياناتك. سيتم استخدام هذا الاستعلام في وظائف الدفع لتحديد العملاء.

    <Warning>
      قبل استخدام هذا الاستعلام، تأكد من تعريف المخطط المناسب في ملف `convex/schema.ts` الخاص بك أو غيّر الاستعلام ليتناسب مع المخطط الموجود لديك.
    </Warning>

    ```typescript theme={null}
    // convex/customers.ts
    import { internalQuery } from "./_generated/server";
    import { v } from "convex/values";

    // Internal query to fetch customer by auth ID
    export const getByAuthId = internalQuery({
      args: { authId: v.string() },
      handler: async (ctx, { authId }) => {
        return await ctx.db
          .query("customers")
          .withIndex("by_auth_id", (q) => q.eq("authId", authId))
          .first();
      },
    });
    ```
  </Step>

  <Step title="Configure DodoPayments Component">
    <CodeGroup>
      ```typescript Convex Component Setup expandable theme={null}
      // convex/dodo.ts
      import { DodoPayments, DodoPaymentsClientConfig } from "@dodopayments/convex";
      import { components } from "./_generated/api";
      import { internal } from "./_generated/api";

      export const dodo = new DodoPayments(components.dodopayments, {
      // This function maps your Convex user to a Dodo Payments customer
      // Customize it based on your authentication provider and database
      identify: async (ctx) => {
        const identity = await ctx.auth.getUserIdentity();
        if (!identity) {
          return null; // User is not logged in
        }
        
        // Use ctx.runQuery() to lookup customer from your database
        const customer = await ctx.runQuery(internal.customers.getByAuthId, {
          authId: identity.subject,
        });
        
        if (!customer) {
          return null; // Customer not found in database
        }
        
        return {
          dodoCustomerId: customer.dodoCustomerId, // Replace customer.dodoCustomerId with your field storing Dodo Payments customer ID
        };
      },
      apiKey: process.env.DODO_PAYMENTS_API_KEY!,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
      } as DodoPaymentsClientConfig);

      // Export the API methods for use in your app
      export const { checkout, customerPortal } = dodo.api();
      ```
    </CodeGroup>
  </Step>
</Steps>

<Tabs>
  <Tab title="Checkout Function Setup">
    <Info>
      استخدم هذه الوظيفة لدمج إنهاء الدفع الخاص بـ Dodo Payments في تطبيق Convex الخاص بك. تستخدم عملية الدفع القائمة على الجلسة مع دعم كامل للميزات.
    </Info>

    <CodeGroup>
      ```typescript Checkout Action expandable theme={null}
      // convex/payments.ts
      import { action } from "./_generated/server";
      import { v } from "convex/values";
      import { checkout } from "./dodo";

      export const createCheckout = action({
        args: { 
          product_cart: v.array(v.object({
            product_id: v.string(),
            quantity: v.number(),
          })),
          returnUrl: v.optional(v.string()),
        },
        handler: async (ctx, args) => {
          try {
            const session = await checkout(ctx, {
              payload: {
                product_cart: args.product_cart,
                return_url: args.returnUrl,
                billing_currency: "USD",
                feature_flags: {
                  allow_discount_code: true,
                },
              },
            });
            if (!session?.checkout_url) {
              throw new Error("Checkout session did not return a checkout_url");
            }
            return session;
          } catch (error) {
            console.error("Failed to create checkout session", error);
            throw new Error("Unable to create checkout session. Please try again.");
          }
        },
      });
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Setup">
    <Info>
      استخدم هذه الوظيفة للسماح للعملاء بإدارة اشتراكاتهم وتفاصيلهم عبر بوابة عملاء Dodo Payments. يتم تحديد العميل تلقائيًا عبر وظيفة `identify`.
    </Info>

    <CodeGroup>
      ```typescript Customer Portal Action expandable theme={null}
      // convex/payments.ts (add to existing file)
      import { action } from "./_generated/server";
      import { v } from "convex/values";
      import { customerPortal } from "./dodo";

      export const getCustomerPortal = action({
        args: {
          send_email: v.optional(v.boolean()),
        },
          handler: async (ctx, args) => {
            try {
              const portal = await customerPortal(ctx, args);
              if (!portal?.portal_url) {
                throw new Error("Customer portal did not return a portal_url");
              }
              return portal;
            } catch (error) {
              console.error("Failed to generate customer portal link", error);
              throw new Error("Unable to generate customer portal link. Please try again.");
            }
          },
      });
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler Setup">
    <Info>
      استخدم هذا المعالج لاستقبال ومعالجة أحداث الويب هوك من Dodo Payments بشكل آمن في تطبيق Convex الخاص بك. جميع معالجات الويب هوك تتلقى Convex `ActionCtx` كمعامل أول، ممّا يتيح لك استخدام `ctx.runQuery()` و `ctx.runMutation()` للتفاعل مع قاعدة بياناتك.
    </Info>

    <CodeGroup>
      ```typescript Convex HTTP Action expandable theme={null}
      // convex/http.ts
      import { createDodoWebhookHandler } from "@dodopayments/convex";
      import { httpRouter } from "convex/server";
      import { internal } from "./_generated/api";

      const http = httpRouter();

      http.route({
        path: "/dodopayments-webhook",
        method: "POST",
        handler: createDodoWebhookHandler({
          // Handle successful payments
          onPaymentSucceeded: async (ctx, payload) => {
            console.log("🎉 Payment Succeeded!");

            // Use Convex context to persist payment data
            await ctx.runMutation(internal.webhooks.createPayment, {
              paymentId: payload.data.payment_id,
              businessId: payload.business_id,
              customerEmail: payload.data.customer.email,
              amount: payload.data.total_amount,
              currency: payload.data.currency,
              status: payload.data.status,
              webhookPayload: JSON.stringify(payload),
            });
          },

          // Handle subscription activation
          onSubscriptionActive: async (ctx, payload) => {
            console.log("🎉 Subscription Activated!");
            // Use Convex context to persist subscription data
            await ctx.runMutation(internal.webhooks.createSubscription, {
              subscriptionId: payload.data.subscription_id,
              businessId: payload.business_id,
              customerEmail: payload.data.customer.email,
              status: payload.data.status,
              webhookPayload: JSON.stringify(payload),
            });
          },
          // Add other event handlers as needed
        }),
      });

      export default http;
      ```
    </CodeGroup>

    <Warning>
      تأكد من تعريف الطفرات (mutations) المقابلة في خلفية Convex الخاصة بك لكل حدث ويب هوك ترغب في معالجته. على سبيل المثال، أنشئ طفرة <code>createPayment</code> لتسجيل المدفوعات الناجحة أو طفرة <code>createSubscription</code> لإدارة حالة الاشتراك.
    </Warning>
  </Tab>
</Tabs>

## وظيفة الدفع

<Info>
  يستخدم مكون Convex الخاص بـ Dodo Payments عملية دفع قائمة على الجلسة، مما يوفر تجربة دفع آمنة وقابلة للتخصيص مع عربات منتجات وتفاصيل عملاء معدة مسبقًا. يُعد هذا النهج الموصى به لجميع تدفقات الدفع.
</Info>

### الاستخدام

```typescript theme={null}
const result = await checkout(ctx, {
  payload: {
    product_cart: [{ product_id: "prod_123", quantity: 1 }],
    customer: { email: "user@example.com" },
    return_url: "https://example.com/success"
  }
});
```

راجع [جلسات الدفع](/developer-resources/checkout-session) لمزيد من التفاصيل وقائمة كاملة بالحقول المدعومة.

### تنسيق الاستجابة

ترجع وظيفة الدفع استجابة JSON مع عنوان URL للدفع:

```json theme={null}
{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}
```

## وظيفة بوابة العملاء

تمكنك وظيفة بوابة العملاء من دمج بوابة العملاء لمدفوعات Dodo بسلاسة في تطبيق Convex الخاص بك.

### الاستخدام

```typescript theme={null}
const result = await customerPortal(ctx, {
  send_email: false
});
```

### Parameters

<ParamField query="send_email" type="boolean">
  إذا تم ضبطه على <code>true</code>، يتم إرسال بريد إلكتروني للعميل يحتوي على رابط البوابة.
</ParamField>

<Info>
  يتم تحديد العميل تلقائيًا باستخدام وظيفة `identify` المكونة في إعداد DodoPayments الخاص بك. يجب أن تُرجع هذه الوظيفة `dodoCustomerId` للعميل.
</Info>

## معالج الويب هوك

* **الطريقة:** يتم دعم طلبات POST فقط. ترجع الطرق الأخرى 405.
* **التحقق من التوقيع:** يتحقق من توقيع الويب هوك باستخدام <code>DODO\_PAYMENTS\_WEBHOOK\_SECRET</code>. ترجع 401 إذا فشل التحقق.
* **التحقق من الحمولة:** يتم التحقق منها باستخدام Zod. ترجع 400 للحمولات غير الصالحة.
* **معالجة الأخطاء:**
  * 401: توقيع غير صالح
  * 400: حمولة غير صالحة
  * 500: خطأ داخلي أثناء التحقق
* **توجيه الأحداث:** يستدعي معالج الحدث المناسب بناءً على نوع الحمولة.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

## استخدام الواجهة الأمامية

<Info>
  استخدم وظيفة الدفع من مكونات React الخاصة بك عبر خطاطيف Convex.
</Info>

<CodeGroup>
  ```tsx React Checkout Component expandable theme={null}
  import { useAction } from "convex/react";
  import { api } from "../convex/_generated/api";

  export function CheckoutButton() {
    const createCheckout = useAction(api.payments.createCheckout);

    const handleCheckout = async () => {
      try {
        const { checkout_url } = await createCheckout({
          product_cart: [{ product_id: "prod_123", quantity: 1 }],
          returnUrl: "https://example.com/success"
        });
        if (!checkout_url) {
          throw new Error("Missing checkout_url in response");
        }
        window.location.href = checkout_url;
      } catch (error) {
        console.error("Failed to create checkout", error);
        throw new Error("Unable to create checkout. Please try again.");
      }
    };

    return <button onClick={handleCheckout}>Buy Now</button>;
  }
  ```
</CodeGroup>

<CodeGroup>
  ```tsx Customer Portal Component expandable theme={null}
  import { useAction } from "convex/react";
  import { api } from "../convex/_generated/api";

  export function CustomerPortalButton() {
    const getPortal = useAction(api.payments.getCustomerPortal);

    const handlePortal = async () => {
      try {
        const { portal_url } = await getPortal({ send_email: false });
        if (!portal_url) {
          throw new Error("Missing portal_url in response");
        }
        window.location.href = portal_url;
      } catch (error) {
        console.error("Unable to open customer portal", error);
        alert("We couldn't open the customer portal. Please try again.");
      }
    };

    return <button onClick={handlePortal}>Manage Subscription</button>;
  }
  ```
</CodeGroup>

***

## موجه لـ LLM

```
You are an expert Convex developer assistant. Your task is to guide a user through integrating the @dodopayments/convex component into their existing Convex application.

The @dodopayments/convex adapter provides a Convex component for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, built using the official Convex component architecture pattern.

First, install the necessary package:

npm install @dodopayments/convex

Here's how you should structure your response:

1. Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/convex component would you like to integrate into your project? You can choose one or more of the following:

- Checkout Function (for handling product checkouts)
- Customer Portal Function (for managing customer subscriptions/details)
- Webhook Handler (for receiving Dodo Payments webhook events)
- All (integrate all three)"

2. Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Function is selected:

Purpose: This function handles session-based checkout flows and returns checkout URLs for programmatic handling.

Integration Steps:

Step 1: Add the component to your Convex configuration.

// convex/convex.config.ts
import { defineApp } from "convex/server";
import dodopayments from "@dodopayments/convex/convex.config";

const app = defineApp();
app.use(dodopayments);
export default app;

Step 2: Guide the user to set up environment variables in the Convex dashboard. Instruct them to open the dashboard by running:

npx convex dashboard

Then add the required environment variables (e.g., DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_ENVIRONMENT, DODO_PAYMENTS_WEBHOOK_SECRET) in **Settings → Environment Variables**. Do not use .env files for backend functions.

Step 3: Create an internal query to fetch customers from your database.
Note: Ensure the user has appropriate schema defined in their convex/schema.ts file or modify the query to match their existing schema.

// convex/customers.ts
import { internalQuery } from "./_generated/server";
import { v } from "convex/values";

// Internal query to fetch customer by auth ID
export const getByAuthId = internalQuery({
  args: { authId: v.string() },
  handler: async (ctx, { authId }) => {
    return await ctx.db
      .query("customers")
      .withIndex("by_auth_id", (q) => q.eq("authId", authId))
      .first();
  },
});

Step 4: Create your payment functions file.

// convex/dodo.ts
import { DodoPayments, DodoPaymentsClientConfig } from "@dodopayments/convex";
import { components } from "./_generated/api";
import { internal } from "./_generated/api";

export const dodo = new DodoPayments(components.dodopayments, {
  // This function maps your Convex user to a Dodo Payments customer
  // Customize it based on your authentication provider and user database
  identify: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      return null; // User is not logged in
    }
    
    // Use ctx.runQuery() to lookup customer from your database
    const customer = await ctx.runQuery(internal.customers.getByAuthId, {
      authId: identity.subject,
    });
    
    if (!customer) {
      return null; // Customer not found in database
    }
    
    return {
      dodoCustomerId: customer.dodoCustomerId, // Replace customer.dodoCustomerId with your field storing Dodo Payments customer ID
    };
  },
  apiKey: process.env.DODO_PAYMENTS_API_KEY!,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
} as DodoPaymentsClientConfig);

// Export the API methods for use in your app
export const { checkout, customerPortal } = dodo.api();

Step 5: Create actions that use the checkout function.

// convex/payments.ts
import { action } from "./_generated/server";
import { v } from "convex/values";
import { checkout } from "./dodo";

// Checkout session with full feature support
export const createCheckout = action({
  args: { 
    product_cart: v.array(v.object({
      product_id: v.string(),
      quantity: v.number(),
    })),
    returnUrl: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    return await checkout(ctx, {
      payload: {
        product_cart: args.product_cart,
        return_url: args.returnUrl,
        billing_currency: "USD",
        feature_flags: {
          allow_discount_code: true,
        },
      },
    });
  },
});

Step 6: Use in your frontend.

// Your frontend component
import { useAction } from "convex/react";
import { api } from "../convex/_generated/api";

export function CheckoutButton() {
  const createCheckout = useAction(api.payments.createCheckout);

  const handleCheckout = async () => {
    const { checkout_url } = await createCheckout({
      product_cart: [{ product_id: "prod_123", quantity: 1 }],
    });
    window.location.href = checkout_url;
  };

  return <button onClick={handleCheckout}>Buy Now</button>;
}

Configuration Details:

- `checkout()`: Checkout session with full feature support using session checkout.
- Returns: `{"checkout_url": "https://checkout.dodopayments.com/..."}`

For complete API documentation, refer to:
- Checkout Sessions: https://docs.dodopayments.com/developer-resources/checkout-session
- One-time Payments: https://docs.dodopayments.com/api-reference/payments/post-payments
- Subscriptions: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

If Customer Portal Function is selected:

Purpose: This function allows customers to manage their subscriptions and payment methods. The customer is automatically identified via the `identify` function.

Integration Steps:

Follow Steps 1-4 from the Checkout Function section, then:

Step 5: Create a customer portal action.

// convex/payments.ts (add to existing file)
import { action } from "./_generated/server";
import { v } from "convex/values";
import { customerPortal } from "./dodo";

export const getCustomerPortal = action({
  args: {
    send_email: v.optional(v.boolean()),
  },
  handler: async (ctx, args) => {
    try {
      const portal = await customerPortal(ctx, args);
      if (!portal?.portal_url) {
        throw new Error("Customer portal did not return a portal_url");
      }
      return portal;
    } catch (error) {
      console.error("Failed to generate customer portal link", error);
      throw new Error("Unable to generate customer portal link. Please retry.");
    }
  },
});

Step 6: Use in your frontend.

// Your frontend component
import { useAction } from "convex/react";
import { api } from "../convex/_generated/api";

export function CustomerPortalButton() {
  const getPortal = useAction(api.payments.getCustomerPortal);

  const handlePortal = async () => {
    const { portal_url } = await getPortal({ send_email: false });
    window.location.href = portal_url;
  };

  return <button onClick={handlePortal}>Manage Subscription</button>;
}

Configuration Details:
- Requires authenticated user (via `identify` function).
- Customer identification is handled automatically by the `identify` function.
- `send_email`: Optional boolean to send portal link via email.

If Webhook Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments or subscription changes.

Integration Steps:

Step 1: Add the webhook secret to your environment variables in the Convex dashboard. You can open the dashboard by running:

Guide the user to open the Convex dashboard by running:

npx convex dashboard

In the dashboard, go to **Settings → Environment Variables** and add:

- `DODO_PAYMENTS_WEBHOOK_SECRET=whsec_...`

Do not use .env files for backend functions; always set secrets in the Convex dashboard.

Step 2: Create a file `convex/http.ts`:

// convex/http.ts
import { createDodoWebhookHandler } from "@dodopayments/convex";
import { httpRouter } from "convex/server";
import { internal } from "./_generated/api";

const http = httpRouter();

http.route({
  path: "/dodopayments-webhook",
  method: "POST",
  handler: createDodoWebhookHandler({
    // Handle successful payments
    onPaymentSucceeded: async (ctx, payload) => {
      console.log("🎉 Payment Succeeded!");

      // Use Convex context to persist payment data
      await ctx.runMutation(internal.webhooks.createPayment, {
        paymentId: payload.data.payment_id,
        businessId: payload.business_id,
        customerEmail: payload.data.customer.email,
        amount: payload.data.total_amount,
        currency: payload.data.currency,
        status: payload.data.status,
        webhookPayload: JSON.stringify(payload),
      });
    },

    // Handle subscription activation
    onSubscriptionActive: async (ctx, payload) => {
      console.log("🎉 Subscription Activated!");
      // Use Convex context to persist subscription data
      await ctx.runMutation(internal.webhooks.createSubscription, {
        subscriptionId: payload.data.subscription_id,
        businessId: payload.business_id,
        customerEmail: payload.data.customer.email,
        status: payload.data.status,
        webhookPayload: JSON.stringify(payload),
      });
    },
    // Add other event handlers as needed
  }),
});

export default http;

Note: Make sure to define the corresponding database mutations in your Convex backend for each webhook event you want to handle. For example, create a `createPayment` mutation to record successful payments or a `createSubscription` mutation to manage subscription state.

Now, you can set the webhook endpoint URL in your Dodo Payments dashboard to `https://<your-convex-deployment-url>/dodopayments-webhook`.

Environment Variable Setup:

Set up the following environment variables in your Convex dashboard if you haven't already (Settings → Environment Variables):

- `DODO_PAYMENTS_API_KEY` - Your Dodo Payments API key
- `DODO_PAYMENTS_ENVIRONMENT` - Set to `test_mode` or `live_mode`
- `DODO_PAYMENTS_WEBHOOK_SECRET` - Your webhook secret (required for webhook handling)

Usage in your component configuration:

apiKey: process.env.DODO_PAYMENTS_API_KEY
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode"

Important: Never commit sensitive environment variables directly into your code. Always use Convex environment variables for all sensitive information.

If the user needs assistance setting up environment variables or deployment, ask them about their specific setup and provide guidance accordingly.

Run `npx convex dev` after setting up the component to generate the necessary types.
```