Webhook Deployment

Overview

Webhooks are critical for keeping your database synchronized with Dodo Payments. When payments are processed or subscriptions change, Dodo Payments sends webhook events to your Supabase Function, which updates your database accordingly.

Prerequisites

Supabase project created (see Supabase Setup)
Database schema deployed (see Database Setup)
Supabase CLI installed (npm install -g supabase or bun install -g supabase)
DODO_WEBHOOK_SECRET from Dodo Payments dashboard

Webhook Function Overview

The webhook function is located at:

supabase/functions/dodo-webhook/index.ts

Function Architecture

The webhook handler:

Verifies webhook signatures using the DODO_WEBHOOK_SECRET
Processes webhook events based on event type
Updates the database with payment and subscription data
Manages user subscription tiers based on subscription status

Handled Event Types

Payment Events

payment.succeeded - Payment completed successfully
payment.failed - Payment attempt failed
payment.processing - Payment is being processed
payment.cancelled - Payment was cancelled

Subscription Events

subscription.active - Subscription is now active (upgrades user tier)
subscription.plan_changed - Subscription plan was changed (updates user tier)
subscription.renewed - Subscription was renewed
subscription.on_hold - Subscription is temporarily on hold
subscription.cancelled - Subscription was cancelled (downgrades user)
subscription.expired - Subscription expired (downgrades user)
subscription.failed - Subscription payment failed (downgrades user)

Deploy the Webhook Function

Authenticate with Supabase:

npx supabase login

This will open a browser window for authentication.

Get your project reference ID

Find your Supabase project reference in your project URL:

https://[your-project-ref].supabase.co

Copy the [your-project-ref] part.

Deploy the webhook function

Run the deployment command:

npm run deploy:webhook -- --project-ref [your-project-ref]

Replace [your-project-ref] with your actual project reference.

The --no-verify-jwt flag is included in the deployment script because webhook endpoints should be publicly accessible without JWT authentication. Security is handled through webhook signature verification instead.

Set environment variables

After deployment, configure the function’s environment variables:

Go to your Supabase project dashboard
Navigate to Edge Functions → dodo-webhook
Click on Settings
Add the following secrets:
- SUPABASE_URL: Your Supabase project URL
- SUPABASE_SERVICE_ROLE_KEY: Your service role key
- DODO_WEBHOOK_SECRET: Your Dodo Payments webhook secret

Alternatively, use the Supabase CLI:

supabase secrets set SUPABASE_URL=https://[your-project-ref].supabase.co --project-ref [your-project-ref]
supabase secrets set SUPABASE_SERVICE_ROLE_KEY=your-service-role-key --project-ref [your-project-ref]
supabase secrets set DODO_WEBHOOK_SECRET=your-webhook-secret --project-ref [your-project-ref]

Get your webhook URL

Your deployed webhook URL will be:

https://[your-project-ref].supabase.co/functions/v1/dodo-webhook

Copy this URL - you’ll need it to configure Dodo Payments.

Configure Dodo Payments Webhook

Navigate to webhook settings

In your Dodo Payments dashboard, go to Settings → Webhooks.

Add webhook endpoint

Click Add Endpoint and enter your webhook URL:

https://[your-project-ref].supabase.co/functions/v1/dodo-webhook

Select events

Choose which events to send to your webhook. For full functionality, select:Payment Events:

payment.succeeded
payment.failed
payment.processing
payment.cancelled

Subscription Events:

subscription.active
subscription.plan_changed
subscription.renewed
subscription.on_hold
subscription.cancelled
subscription.expired
subscription.failed

You can select “All events” to ensure you receive all current and future event types.

Save configuration

Click Save to activate the webhook.Dodo Payments will now send events to your Supabase Function in real-time.

Webhook Function Code Structure

Main Handler

The function uses Deno’s serve API:

Deno.serve(async (req) => {
  // Handle OPTIONS for CORS
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  // Verify webhook signature
  const webhook = new Webhook(dodoWebhookSecret);
  await webhook.verify(rawBody, webhookHeaders);

  // Process event based on type
  switch (event.type) {
    case "payment.succeeded":
      await managePayment(event);
      break;
    case "subscription.active":
      await manageSubscription(event);
      await updateUserTier({...});
      break;
    // ... other event types
  }
});

Key Functions

managePayment()

Upserts payment records to the payments table:

async function managePayment(event: any) {
  const data = {
    payment_id: event.data.payment_id,
    status: event.data.status,
    total_amount: event.data.total_amount,
    // ... other payment fields
  };

  await supabase.from("payments").upsert(data, {
    onConflict: "payment_id",
  });
}

manageSubscription()

Upserts subscription records to the subscriptions table:

async function manageSubscription(event: any) {
  const data = {
    subscription_id: event.data.subscription_id,
    status: event.data.status,
    product_id: event.data.product_id,
    // ... other subscription fields
  };

  await supabase.from("subscriptions").upsert(data, {
    onConflict: "subscription_id",
  });
}

updateUserTier()

Links active subscriptions to user accounts:

async function updateUserTier(props: {
  dodoCustomerId: string;
  subscriptionId: string;
}) {
  await supabase
    .from("users")
    .update({ current_subscription_id: props.subscriptionId })
    .eq("dodo_customer_id", props.dodoCustomerId);
}

downgradeToHobbyPlan()

Removes subscription when cancelled or expired:

async function downgradeToHobbyPlan(props: { dodoCustomerId: string }) {
  await supabase
    .from("users")
    .update({ current_subscription_id: null })
    .eq("dodo_customer_id", props.dodoCustomerId);
}

Testing Your Webhook

Test in Dodo Payments Dashboard

Go to Settings → Webhooks
Find your webhook endpoint
Click Send test event
Select an event type (e.g., payment.succeeded)
Click Send

Monitor Function Logs

View real-time logs in Supabase:

Go to Edge Functions → dodo-webhook
Click on Logs
You’ll see incoming requests and any errors

Verify Database Updates

After sending a test event, check your database:

Go to Database → Table Editor
Select the payments or subscriptions table
Verify that test data appears

Troubleshooting

Webhook signature verification failed

Cause: The DODO_WEBHOOK_SECRET is incorrect or not set.Solution:

Verify the secret in Dodo Payments dashboard matches the one set in Supabase
Check that the secret is properly set in Edge Functions settings
Redeploy the function after updating secrets

Function returns 500 error

Cause: Database connection or environment variable issues.Solution:

Check that SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are set correctly
Verify your database tables exist by running db:push again
Check function logs for specific error messages

Events received but database not updating

Cause: Table structure mismatch or missing fields.Solution:

Ensure your database schema matches the latest version
Run bun run db:push to sync schema changes
Check function logs for SQL errors

CORS errors in logs

Cause: CORS headers not properly configured.Solution: The function includes CORS headers, but if you’re still seeing errors:

Ensure the OPTIONS handler is responding correctly
Check that corsHeaders includes your domain
Verify the request method is allowed

Security Considerations

Important security practices:

Always verify webhook signatures before processing events
Never expose your DODO_WEBHOOK_SECRET in client-side code
Use the SUPABASE_SERVICE_ROLE_KEY only in secure server environments
Monitor webhook logs regularly for suspicious activity
Implement rate limiting if you expect high webhook volume

Overview

Getting Started

Setup Guides

Core Features

Development

Deployment

Overview

Prerequisites

Webhook Function Overview

Function Architecture

Handled Event Types

Payment Events

Subscription Events

Deploy the Webhook Function

Configure Dodo Payments Webhook

Webhook Function Code Structure

Main Handler

Key Functions

managePayment()

manageSubscription()

updateUserTier()

downgradeToHobbyPlan()

Testing Your Webhook

Test in Dodo Payments Dashboard

Monitor Function Logs

Verify Database Updates

Troubleshooting

Security Considerations

Next Steps

Run Development Server

Deploy to Production

Build docs developers (and LLMs) love

Overview

Getting Started

Setup Guides

Core Features

Development

Deployment

​Overview

​Prerequisites

​Webhook Function Overview

​Function Architecture

​Handled Event Types

​Payment Events

​Subscription Events

​Deploy the Webhook Function

​Configure Dodo Payments Webhook

​Webhook Function Code Structure

​Main Handler

​Key Functions

​managePayment()

​manageSubscription()

​updateUserTier()

​downgradeToHobbyPlan()

​Testing Your Webhook

​Test in Dodo Payments Dashboard

​Monitor Function Logs

​Verify Database Updates

​Troubleshooting

​Security Considerations

​Next Steps

Run Development Server

Deploy to Production

Build docs developers (and LLMs) love

Overview

Prerequisites

Webhook Function Overview

Function Architecture

Handled Event Types

Payment Events

Subscription Events

Deploy the Webhook Function

Configure Dodo Payments Webhook

Webhook Function Code Structure

Main Handler

Key Functions

managePayment()

manageSubscription()

updateUserTier()

downgradeToHobbyPlan()

Testing Your Webhook

Test in Dodo Payments Dashboard

Monitor Function Logs

Verify Database Updates

Troubleshooting

Security Considerations

Next Steps