@dodopayments/opencode-plugin 0.3.2 → 0.4.0

package/skills/webhook-integration/SKILL.md

@@ -5,82 +5,62 @@ description: Complete guide for setting up and handling Dodo Payments webhooks f
 
 # Dodo Payments Webhook Integration
 
-**Reference: [docs.dodopayments.com/developer-resources/webhooks](https://docs.dodopayments.com/developer-resources/webhooks)**
+Webhooks deliver real-time notifications when payment events occur. Use them to automate workflows, update databases, send confirmations, and keep your systems in sync.
 
-Webhooks provide real-time notifications when payment events occur. Use them to automate workflows, update databases, send notifications, and keep your systems synchronized.
+## When to use this skill
+
+- Setting up a webhook endpoint to receive payment, subscription, or refund events
+- Implementing signature verification to ensure webhook authenticity
+- Handling specific event types (payment succeeded, subscription renewed, etc.)
+- Testing webhooks locally during development
+- Ensuring idempotent webhook processing to handle retries
 
 ---
 
-## Quick Setup
+## Core Concepts
+
+**Webhook**: An HTTP POST request sent by Dodo to your endpoint when an event occurs.
+
+**Signature verification**: Cryptographic proof that a webhook came from Dodo, not an attacker. Required for production.
+
+**Idempotency**: Processing the same webhook multiple times produces the same result. Use the `webhook-id` header to detect and skip duplicates.
+
+**Raw body**: The exact bytes received from Dodo, before parsing. Required for signature verification.
+
+---
 
-### 1. Configure Webhook in Dashboard
-1. Go to Dashboard → Developer → Webhooks
-2. Click "Create Webhook"
-3. Enter your endpoint URL
-4. Select events to subscribe to
-5. Copy the webhook secret
+## Setup: Creating a Webhook Endpoint
+
+### 1. Create the endpoint in the dashboard
+
+1. Go to **Developer → Webhooks**
+2. Click **Create Webhook**
+3. Enter your endpoint URL (must be HTTPS in production)
+4. Select the events you want to receive
+5. Copy the signing secret
+
+### 2. Store the signing secret
 
-### 2. Environment Variables
 ```bash
-DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
+export DODO_PAYMENTS_WEBHOOK_KEY=whsec_...
 ```
 
----
+The SDK reads this automatically. You can also pass it explicitly when initializing the client.
 
-## Webhook Events
-
-### Payment Events
-| Event | Description |
-|-------|-------------|
-| `payment.succeeded` | Payment completed successfully |
-| `payment.failed` | Payment attempt failed |
-| `payment.processing` | Payment is being processed |
-| `payment.cancelled` | Payment was cancelled |
-
-### Subscription Events
-| Event | Description |
-|-------|-------------|
-| `subscription.active` | Subscription is now active |
-| `subscription.updated` | Subscription details changed |
-| `subscription.on_hold` | Subscription on hold (failed renewal) |
-| `subscription.renewed` | Subscription renewed successfully |
-| `subscription.plan_changed` | Plan upgraded/downgraded |
-| `subscription.cancelled` | Subscription cancelled |
-| `subscription.failed` | Subscription creation failed |
-| `subscription.expired` | Subscription term ended |
-
-### Other Events
-| Event | Description |
-|-------|-------------|
-| `refund.succeeded` | Refund processed successfully |
-| `dispute.opened` | New dispute received |
-| `license_key.created` | License key generated |
-
-### Credit Events
-| Event | Description |
-|-------|-------------|
-| `credit.added` | Credits granted to a customer (subscription, one-time, or API) |
-| `credit.deducted` | Credits consumed through usage or manual debit |
-| `credit.expired` | Unused credits expired after configured period |
-| `credit.rolled_over` | Unused credits carried forward at cycle end |
-| `credit.rollover_forfeited` | Credits forfeited at max rollover count |
-| `credit.overage_charged` | Overage charges applied beyond zero balance |
-| `credit.manual_adjustment` | Manual credit/debit adjustment via dashboard or API |
-| `credit.balance_low` | Credit balance dropped below configured threshold |
 ---
 
-## Webhook Payload Structure
+## Webhook Headers and Payload
 
-### Request Headers
-```http
-POST /your-webhook-url
-Content-Type: application/json
-webhook-id: evt_xxxxx
-webhook-signature: v1,signature_here
-webhook-timestamp: 1234567890
-```
+Every webhook request includes three required headers (all lowercase, hyphenated):
+
+| Header | Example | Purpose |
+|--------|---------|---------|
+| `webhook-id` | `evt_abc123` | Unique identifier for this webhook delivery |
+| `webhook-signature` | `v1,base64_signature_here` | HMAC-SHA256 signature for verification |
+| `webhook-timestamp` | `1704067200` | Unix timestamp (seconds) when the event was sent |
+
+The request body is JSON:
 
-### Payload Format
 ```json
 {
   "business_id": "bus_xxxxx",
@@ -89,441 +69,659 @@ webhook-timestamp: 1234567890
   "data": {
     "payload_type": "Payment",
     "payment_id": "pay_xxxxx",
+    "status": "succeeded",
     "total_amount": 2999,
     "currency": "USD",
     "customer": {
-      "customer_id": "cust_xxxxx",
+      "customer_id": "cus_xxxxx",
       "email": "customer@example.com",
       "name": "John Doe"
     }
-    // ... additional event-specific fields
   }
 }
 ```
 
 ---
 
-## Implementation Examples
+## Verification: The Centerpiece
+
+**Always verify the signature before processing.** Unverified webhooks can be spoofed.
+
+### Preferred: SDK helper
+
+The simplest and safest approach. The SDK handles all verification details.
 
-### Next.js (App Router)
+**TypeScript/Node:**
 
 ```typescript
-// app/api/webhooks/dodo/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import crypto from 'crypto';
-
-const WEBHOOK_SECRET = process.env.DODO_PAYMENTS_WEBHOOK_SECRET!;
-
-function verifySignature(payload: string, signature: string, timestamp: string): boolean {
-  const signedPayload = `${timestamp}.${payload}`;
-  const expectedSignature = crypto
-    .createHmac('sha256', WEBHOOK_SECRET)
-    .update(signedPayload)
-    .digest('base64');
-  
-  // Extract signature from "v1,signature" format
-  const providedSig = signature.split(',')[1];
-  
-  return crypto.timingSafeEqual(
-    Buffer.from(expectedSignature),
-    Buffer.from(providedSig || '')
-  );
-}
+import DodoPayments from 'dodopayments';
+import express from 'express';
 
-export async function POST(req: NextRequest) {
-  const body = await req.text();
-  const signature = req.headers.get('webhook-signature') || '';
-  const timestamp = req.headers.get('webhook-timestamp') || '';
-  const webhookId = req.headers.get('webhook-id');
+const app = express();
+app.use(express.raw({ type: 'application/json' }));
 
-  // Verify signature
-  if (!verifySignature(body, signature, timestamp)) {
-    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
-  }
+// `environment` is a narrow union, but env vars are `string | undefined`.
+// Narrow explicitly rather than casting, and default to test mode so a missing
+// variable can never accidentally hit live.
+const environment = process.env.DODO_PAYMENTS_ENVIRONMENT === 'live_mode' ? 'live_mode' : 'test_mode';
 
-  // Check timestamp to prevent replay attacks (5 minute tolerance)
-  const eventTime = parseInt(timestamp) * 1000;
-  if (Math.abs(Date.now() - eventTime) > 300000) {
-    return NextResponse.json({ error: 'Timestamp too old' }, { status: 401 });
-  }
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  environment,
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+});
 
-  const event = JSON.parse(body);
-
-  // Handle events
-  switch (event.type) {
-    case 'payment.succeeded':
-      await handlePaymentSucceeded(event.data);
-      break;
-    case 'payment.failed':
-      await handlePaymentFailed(event.data);
-      break;
-    case 'subscription.active':
-      await handleSubscriptionActive(event.data);
-      break;
-    case 'subscription.cancelled':
-      await handleSubscriptionCancelled(event.data);
-      break;
-    case 'refund.succeeded':
-      await handleRefundSucceeded(event.data);
-      break;
-    case 'dispute.opened':
-      await handleDisputeOpened(event.data);
-      break;
-    case 'license_key.created':
-      await handleLicenseKeyCreated(event.data);
-      break;
-    case 'credit.added':
-      await handleCreditAdded(event.data);
-      break;
-    case 'credit.deducted':
-      await handleCreditDeducted(event.data);
-      break;
-    case 'credit.balance_low':
-      await handleCreditBalanceLow(event.data);
-      break;
-    default:
-      console.log(`Unhandled event type: ${event.type}`);
+app.post('/webhook', async (req, res) => {
+  try {
+    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
+      headers: {
+        'webhook-id': req.headers['webhook-id'] as string,
+        'webhook-signature': req.headers['webhook-signature'] as string,
+        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
+      },
+    });
+    
+    // Signature verified. Process the event.
+    console.log(`Received ${unwrapped.type}`);
+    res.json({ received: true });
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid signature' });
   }
+});
+```
 
-  return NextResponse.json({ received: true });
-}
+**Python:**
 
-async function handlePaymentSucceeded(data: any) {
-  const { payment_id, customer, total_amount, product_id, subscription_id } = data;
-  
-  // Update database
-  // Send confirmation email
-  // Grant access to product
-  console.log(`Payment ${payment_id} succeeded for ${customer.email}`);
-}
+```python
+from typing import Literal
+from fastapi import FastAPI, Request, HTTPException
+from dodopayments import DodoPayments
+import os
+
+# `environment` is Literal["live_mode", "test_mode"], not str. Passing the raw
+# variable through raises at construction: unset gives
+# `ValueError: Unknown environment: None`, and a typo like "test" gives
+# `Unknown environment: test`. Narrow it, defaulting to test mode so a
+# misconfigured variable can never select live.
+ENVIRONMENT: Literal["live_mode", "test_mode"] = (
+    "live_mode" if os.getenv("DODO_PAYMENTS_ENVIRONMENT") == "live_mode" else "test_mode"
+)
 
-async function handlePaymentFailed(data: any) {
-  const { payment_id, customer, error_message } = data;
-  
-  // Log failure
-  // Notify customer
-  // Update UI state
-  console.log(`Payment ${payment_id} failed: ${error_message}`);
-}
+app = FastAPI()
+client = DodoPayments(
+    bearer_token=os.getenv("DODO_PAYMENTS_API_KEY"),
+    environment=ENVIRONMENT,
+    webhook_key=os.getenv("DODO_PAYMENTS_WEBHOOK_KEY"),
+)
 
-async function handleSubscriptionActive(data: any) {
-  const { subscription_id, customer, product_id, next_billing_date } = data;
-  
-  // Grant subscription access
-  // Update user record
-  // Send welcome email
-  console.log(`Subscription ${subscription_id} activated for ${customer.email}`);
-}
+@app.post("/webhook")
+async def handle_webhook(request: Request):
+    try:
+        unwrapped = client.webhooks.unwrap(
+            await request.body(),
+            headers={
+                "webhook-id": request.headers.get("webhook-id", ""),
+                "webhook-signature": request.headers.get("webhook-signature", ""),
+                "webhook-timestamp": request.headers.get("webhook-timestamp", ""),
+            },
+        )
+        # Signature verified. Process the event.
+        return {"received": True}
+    except Exception:
+        raise HTTPException(status_code=401, detail="Invalid signature")
+```
 
-async function handleSubscriptionCancelled(data: any) {
-  const { subscription_id, customer, cancelled_at, cancel_at_next_billing_date } = data;
-  
-  // Schedule access revocation
-  // Send cancellation confirmation
-  console.log(`Subscription ${subscription_id} cancelled`);
-}
+**Go:**
 
-async function handleRefundSucceeded(data: any) {
-  const { refund_id, payment_id, amount } = data;
-  
-  // Update order status
-  // Revoke access if needed
-  console.log(`Refund ${refund_id} processed for payment ${payment_id}`);
-}
+```go
+import (
+	"io"
+	"net/http"
+	"os"
 
-async function handleDisputeOpened(data: any) {
-  const { dispute_id, payment_id, amount, dispute_status } = data;
-  
-  // Alert team
-  // Prepare evidence
-  console.log(`Dispute ${dispute_id} opened for payment ${payment_id}`);
-}
+	"github.com/dodopayments/dodopayments-go"
+	"github.com/dodopayments/dodopayments-go/option"
+)
 
-async function handleLicenseKeyCreated(data: any) {
-  const { id, key, product_id, customer_id, expires_at } = data;
-  
-  // Store license key
-  // Send to customer
-  console.log(`License key created: ${key.substring(0, 8)}...`);
+// The Go SDK has no WithEnvironment(string). It exposes two explicit options,
+// so narrow here and default to test mode: an unset or misspelled variable must
+// never select live mode.
+func dodoEnvironment() option.RequestOption {
+	if os.Getenv("DODO_PAYMENTS_ENVIRONMENT") == "live_mode" {
+		return option.WithEnvironmentLiveMode()
+	}
+	return option.WithEnvironmentTestMode()
 }
 
-async function handleCreditAdded(data: any) {
-  const { customer_id, credit_entitlement_id, amount, balance_after } = data;
-  
-  // Update internal credit balance
-  // Log credit grant
-  console.log(`${amount} credits added for customer ${customer_id}, balance: ${balance_after}`);
+func webhookHandler(w http.ResponseWriter, r *http.Request) {
+	client := dodopayments.NewClient(
+		option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
+		dodoEnvironment(),
+		option.WithWebhookKey(os.Getenv("DODO_PAYMENTS_WEBHOOK_KEY")),
+	)
+
+	rawBody, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "Cannot read body", http.StatusBadRequest)
+		return
+	}
+
+	// Unwrap takes the raw body and the request headers directly. It is not
+	// context-aware and does not take a map: the signature is
+	// Unwrap(payload []byte, headers http.Header, opts ...option.RequestOption).
+	if _, err := client.Webhooks.Unwrap(rawBody, r.Header); err != nil {
+		http.Error(w, "Invalid signature", http.StatusUnauthorized)
+		return
+	}
+
+	// Signature verified. Process the event.
+	w.WriteHeader(http.StatusOK)
 }
+```
 
-async function handleCreditDeducted(data: any) {
-  const { customer_id, credit_entitlement_id, amount, balance_after } = data;
-  
-  // Update internal credit balance
-  // Check if balance is getting low
-  console.log(`${amount} credits deducted for customer ${customer_id}, balance: ${balance_after}`);
-}
+### Alternative: `standardwebhooks` package
 
-async function handleCreditBalanceLow(data: any) {
-  const { customer_id, credit_entitlement_name, available_balance, threshold_percent } = data;
-  
-  // Notify customer about low balance
-  // Suggest upgrading plan or purchasing more credits
-  console.log(`Low balance alert: ${available_balance} ${credit_entitlement_name} remaining for ${customer_id}`);
-}
+If you prefer manual verification or don't use the Dodo SDK:
+
+```typescript
+import { Webhook } from "standardwebhooks";
+import express from "express";
+
+const app = express();
+app.use(express.raw({ type: "application/json" }));
+
+const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);
+
+app.post("/webhooks/dodo", async (req, res) => {
+  try {
+    const payload = req.body.toString();
+    await webhook.verify(payload, req.headers);
+    
+    const event = JSON.parse(payload);
+    console.log(`Received ${event.type}`);
+    res.json({ received: true });
+  } catch (error) {
+    res.status(401).json({ error: "Invalid signature" });
+  }
+});
 ```
 
-### Express.js
+### `unwrap()` vs `unsafeUnwrap()`
+
+- `unwrap()` verifies the signature. Use this for all production webhooks.
+- `unsafeUnwrap()` skips verification. Use only for unsigned test payloads from `dodo wh trigger`.
+
+---
+
+## Raw Body Requirement
+
+Signature verification requires the exact bytes Dodo sent. If you parse the JSON first and then re-serialize it, the bytes change and verification fails.
+
+**Framework-specific setup:**
+
+| Framework | Raw body setup |
+|-----------|---|
+| **Express** | `app.use(express.raw({ type: 'application/json' }))` |
+| **Next.js** | `req.text()` in route handlers; no middleware needed |
+| **Fastify** | Custom content-type parser (see adaptor docs) |
+| **Hono** | Built-in; no special setup |
+| **FastAPI** | `await request.body()` returns bytes |
+| **Go** | `io.ReadAll(r.Body)` |
+
+---
+
+## Webhook Event Catalog
+
+Dodo sends 40+ event types across nine domains. Subscribe to only the events you need.
+
+### Payment events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `payment.succeeded` | Payment completed successfully | Grant access, send confirmation, update order status |
+| `payment.failed` | Payment attempt failed | Notify customer, suggest retry or alternative payment method |
+| `payment.processing` | Payment is still being processed | Acknowledge receipt, wait for `payment.succeeded` or `payment.failed` |
+| `payment.cancelled` | Payment was cancelled before completion | Update order status, notify customer if applicable |
+
+### Subscription events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `subscription.active` | Subscription becomes active; recurring charges are scheduled | Grant subscription access, send welcome email |
+| `subscription.updated` | Any field on the subscription changes | Sync changes to your database |
+| `subscription.on_hold` | Failed renewal temporarily pauses the subscription | Notify customer, prompt payment method update |
+| `subscription.renewed` | Subscription amount successfully deducted for a billing period | Log renewal, update next billing date |
+| `subscription.plan_changed` | Plan upgraded, downgraded, or modified | Update customer's access level or feature set |
+| `subscription.update_payment_method` | Payment method is updated | Sync the new payment method to your records |
+| `subscription.cancelled` | Merchant or customer cancels the subscription | Revoke access, send cancellation confirmation |
+| `subscription.failed` | Subscription creation fails (mandate creation failed) | Notify customer, suggest alternative payment method |
+| `subscription.expired` | Subscription reaches the end of its term | Revoke access, offer renewal or upgrade |
+
+### Refund events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `refund.succeeded` | Refund successfully processed | Update order status, revoke access if applicable |
+| `refund.failed` | Refund processing fails | Alert team, investigate reason |
+
+### Dispute events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `dispute.opened` | Customer initiates a dispute | Alert team, prepare evidence |
+| `dispute.expired` | Dispute expires without resolution | Log outcome |
+| `dispute.accepted` | Merchant accepts the dispute | Process refund if not already done |
+| `dispute.cancelled` | Customer or system cancels the dispute | Log outcome |
+| `dispute.challenged` | Merchant challenges the dispute | Prepare additional evidence |
+| `dispute.won` | Merchant wins the dispute | Log outcome, retain funds |
+| `dispute.lost` | Merchant loses the dispute | Process refund, log outcome |
+
+### License key events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `license_key.created` | License key is generated | Send key to customer (legacy; prefer `entitlement_grant.delivered`) |
+
+### Entitlement grant events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `entitlement_grant.created` | Grant row is created | Prepare for fulfillment |
+| `entitlement_grant.delivered` | Fulfillment completes; customer receives access | Grant platform, file, or license-key access |
+| `entitlement_grant.failed` | Delivery fails and is no longer retried | Alert team, inspect `error_code` and `error_message` |
+| `entitlement_grant.revoked` | Access is withdrawn | Revoke customer access, inspect `revocation_reason` |
+
+### Credit events
+
+These concern virtual credit entitlements, not monetary wallet balances.
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `credit.added` | Credits granted via subscription, purchase, add-on, or API | Update internal credit balance, log grant |
+| `credit.deducted` | Usage or manual debit consumes credits | Update internal credit balance |
+| `credit.expired` | Unused credits reach expiry | Log expiration, notify customer if applicable |
+| `credit.rolled_over` | Unused credits carried into a new grant | Update internal balance |
+| `credit.rollover_forfeited` | Credits forfeited at max rollover count | Log forfeiture |
+| `credit.overage_charged` | Overage charged after usage exceeds balance | Update internal balance, notify customer |
+| `credit.overage_reset` | Accumulated overage reset (e.g., new billing cycle) | Update internal balance |
+| `credit.manual_adjustment` | Manual credit or debit adjustment made | Update internal balance, log adjustment |
+| `credit.balance_low` | Balance falls below configured threshold | Notify customer, suggest purchase |
+
+### Recovery and dunning events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `abandoned_checkout.detected` | Failed or incomplete checkout classified as abandoned (after 60 min) | Monitor recovery link usage |
+| `abandoned_checkout.recovered` | Customer pays through recovery link | Log recovery, update order status |
+| `dunning.started` | Dunning attempt begins after subscription enters `on_hold` | Monitor dunning progress |
+| `dunning.recovered` | Customer updates payment method and charge succeeds | Reactivate subscription, send confirmation |
+
+---
+
+## Production-Grade Handler Pattern
+
+Respond quickly after durably recording the event, process asynchronously, and use idempotency keys. In the worker, insert the idempotency claim and apply all durable business changes in one database transaction. If processing throws, the transaction rolls back the claim so the job can retry safely:
 
 ```typescript
+import DodoPayments from 'dodopayments';
 import express from 'express';
-import crypto from 'crypto';
+import { Queue, Worker } from 'bullmq';
+
+// BullMQ is illustrative; use your preferred durable async queue.
 
 const app = express();
-const WEBHOOK_SECRET = process.env.DODO_PAYMENTS_WEBHOOK_SECRET!;
-
-// Use raw body for signature verification
-app.post('/webhooks/dodo', 
-  express.raw({ type: 'application/json' }),
-  async (req, res) => {
-    const signature = req.headers['webhook-signature'] as string;
-    const timestamp = req.headers['webhook-timestamp'] as string;
-    const payload = req.body.toString();
+app.use(express.raw({ type: 'application/json' }));
 
-    // Verify signature
-    const signedPayload = `${timestamp}.${payload}`;
-    const expectedSig = crypto
-      .createHmac('sha256', WEBHOOK_SECRET)
-      .update(signedPayload)
-      .digest('base64');
-    
-    const providedSig = signature?.split(',')[1];
-    
-    if (!providedSig || !crypto.timingSafeEqual(
-      Buffer.from(expectedSig),
-      Buffer.from(providedSig)
-    )) {
-      return res.status(401).json({ error: 'Invalid signature' });
-    }
+// `environment` is a narrow union, but env vars are `string | undefined`.
+// Narrow explicitly rather than casting, and default to test mode so a missing
+// variable can never accidentally hit live.
+const environment = process.env.DODO_PAYMENTS_ENVIRONMENT === 'live_mode' ? 'live_mode' : 'test_mode';
 
-    const event = JSON.parse(payload);
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  environment,
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+});
+
+type WebhookEvent = ReturnType<typeof client.webhooks.unwrap>;
+type WebhookJob = { event: WebhookEvent; webhookId: string };
+
+const connection = {
+  host: process.env.REDIS_HOST ?? '127.0.0.1',
+  port: Number(process.env.REDIS_PORT ?? '6379'),
+};
+const eventQueue = new Queue<WebhookJob>('webhook-events', { connection });
+
+app.post('/webhook', async (req, res) => {
+  let unwrapped: WebhookEvent;
+  
+  try {
+    unwrapped = client.webhooks.unwrap(req.body.toString(), {
+      headers: {
+        'webhook-id': req.headers['webhook-id'] as string,
+        'webhook-signature': req.headers['webhook-signature'] as string,
+        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
+      },
+    });
+  } catch (error) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+  
+  // Durably enqueue before acknowledging, keyed by webhook-id for idempotency
+  const webhookId = req.headers['webhook-id'] as string;
+  try {
+    await eventQueue.add(
+      `process-${unwrapped.type}`,
+      { event: unwrapped, webhookId },
+      {
+        jobId: webhookId, // Prevents duplicate queue entries
+        attempts: 8,
+        backoff: { type: 'exponential', delay: 1000 },
+      }
+    );
+    return res.json({ received: true });
+  } catch (error) {
+    console.error('Failed to persist webhook', error);
+    return res.status(503).json({ error: 'Webhook persistence failed' });
+  }
+});
+
+// Async worker. webhookLog.webhookId must have a unique constraint.
+const worker = new Worker<WebhookJob>(
+  'webhook-events',
+  async (job) => {
+    const { event, webhookId } = job.data;
+
+    await db.$transaction(async (tx) => {
+      const claim = await tx.webhookLog.createMany({
+        data: [{ webhookId, eventType: event.type }],
+        skipDuplicates: true,
+      });
+      if (claim.count === 0) return;
 
-    // Process event
-    try {
       switch (event.type) {
         case 'payment.succeeded':
-          await processPayment(event.data);
+          await handlePaymentSucceeded(event.data, tx);
           break;
         case 'subscription.active':
-          await activateSubscription(event.data);
+          await handleSubscriptionActive(event.data, tx);
           break;
         // ... handle other events
       }
-      res.json({ received: true });
-    } catch (error) {
-      console.error('Webhook processing error:', error);
-      res.status(500).json({ error: 'Processing failed' });
-    }
-  }
+    });
+  },
+  { connection }
 );
 ```
 
-### Python (FastAPI)
+The handlers above must perform entitlement writes through `tx`. Queue emails or other external work through a transactional outbox; a database transaction cannot roll back an already-sent external request.
 
-```python
-from fastapi import FastAPI, Request, HTTPException
-import hmac
-import hashlib
-import base64
-import time
+---
 
-app = FastAPI()
-WEBHOOK_SECRET = os.environ["DODO_PAYMENTS_WEBHOOK_SECRET"]
-
-def verify_signature(payload: bytes, signature: str, timestamp: str) -> bool:
-    signed_payload = f"{timestamp}.{payload.decode()}"
-    expected_sig = base64.b64encode(
-        hmac.new(
-            WEBHOOK_SECRET.encode(),
-            signed_payload.encode(),
-            hashlib.sha256
-        ).digest()
-    ).decode()
-    
-    provided_sig = signature.split(',')[1] if ',' in signature else ''
-    return hmac.compare_digest(expected_sig, provided_sig)
+## Delivery Semantics
 
-@app.post("/webhooks/dodo")
-async def handle_webhook(request: Request):
-    body = await request.body()
-    signature = request.headers.get("webhook-signature", "")
-    timestamp = request.headers.get("webhook-timestamp", "")
-    
-    if not verify_signature(body, signature, timestamp):
-        raise HTTPException(status_code=401, detail="Invalid signature")
-    
-    # Check timestamp freshness
-    event_time = int(timestamp)
-    if abs(time.time() - event_time) > 300:
-        raise HTTPException(status_code=401, detail="Timestamp too old")
-    
-    event = json.loads(body)
-    
-    if event["type"] == "payment.succeeded":
-        await handle_payment_succeeded(event["data"])
-    elif event["type"] == "subscription.active":
-        await handle_subscription_active(event["data"])
-    # ... handle other events
-    
-    return {"received": True}
+Understand how Dodo delivers webhooks:
+
+| Property | Behavior |
+|----------|----------|
+| **Timeout** | 15 seconds for connection and read |
+| **Success** | Any `2xx` response acknowledges delivery. Return `200` immediately after durably recording the event. |
+| **Failure** | Any non-`2xx` response triggers a retry. |
+| **Retries** | Eight attempts: immediately, 5s, 5m, 30m, 2h, 5h, 10h, 10h |
+| **Idempotency** | Use `webhook-id` to detect and skip duplicates |
+| **Ordering** | No guarantee. Events can arrive out of order. |
+| **Payload freshness** | Delivery contains the latest resource state at delivery time |
+| **Transport** | Use HTTPS in production |
+
+---
+
+## Framework Adaptor Shortcuts
+
+If you use a supported framework, use the official adaptor package for built-in webhook handling:
+
+| Framework | Package | Webhook handler |
+|-----------|---------|---|
+| Next.js | `@dodopayments/nextjs` | `Webhooks({ webhookKey, onPayload })` |
+| Nuxt | `@dodopayments/nuxt` | `Webhooks({ webhookKey, onPayload })` |
+| Express | `@dodopayments/express` | Middleware with raw-body parser |
+| Fastify | `@dodopayments/fastify` | `Webhooks({ webhookKey, onPayload })` |
+| Hono | `@dodopayments/hono` | `Webhooks({ webhookKey, onPayload })` |
+| Astro | `@dodopayments/astro` | `Webhooks({ webhookKey, onPayload })` |
+| SvelteKit | `@dodopayments/sveltekit` | `Webhooks({ webhookKey, onPayload })` |
+| Remix | `@dodopayments/remix` | `Webhooks({ webhookKey, onPayload })` |
+| TanStack Start | `@dodopayments/tanstack` | `Webhooks({ webhookKey, onPayload })` |
+| Bun | `@dodopayments/bun` | `Webhooks({ webhookKey, onPayload })` |
+| Better Auth | `@dodopayments/better-auth` | Plugin with `webhooks({ webhookKey, onPayload })` |
+| Convex | `@dodopayments/convex` | Component with verified HTTP handler |
+
+**Next.js example:**
+
+The adapter callback does not expose `webhook-id`, so this payment example uses `payment_id` as its stable key and commits the claim and durable fulfillment together. Use a handler that exposes `webhook-id` for event types without a verified stable identifier.
+
+```typescript
+// app/api/webhook/dodo-payments/route.ts
+import { Webhooks } from "@dodopayments/nextjs";
+
+export const POST = Webhooks({
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+  onPayload: async (payload) => {
+    // payload is already verified
+    console.log(`Received ${payload.type}`);
+
+    if (payload.type !== 'payment.succeeded') return;
+
+    // webhookLog.webhookId must have a unique constraint. If fulfillment
+    // throws, the claim rolls back and Dodo's redelivery can retry it.
+    await db.$transaction(async (tx) => {
+      const claim = await tx.webhookLog.createMany({
+        data: [{
+          webhookId: payload.data.payment_id,
+          eventType: payload.type,
+        }],
+        skipDuplicates: true,
+      });
+      if (claim.count === 0) return;
+
+      await handlePaymentSucceeded(payload.data, tx);
+    });
+  },
+});
 ```
 
-### Go
+Handle `subscription.active` only in a handler that exposes `webhook-id`, then commit that claim and the entitlement changes in the same transaction.
 
-```go
-package main
+---
 
-import (
-    "crypto/hmac"
-    "crypto/sha256"
-    "encoding/base64"
-    "encoding/json"
-    "io"
-    "net/http"
-    "os"
-    "strconv"
-    "strings"
-    "time"
-)
+## Local Testing
 
-var webhookSecret = os.Getenv("DODO_PAYMENTS_WEBHOOK_SECRET")
+### Dashboard test tool
 
-func verifySignature(payload []byte, signature, timestamp string) bool {
-    signedPayload := timestamp + "." + string(payload)
-    
-    mac := hmac.New(sha256.New, []byte(webhookSecret))
-    mac.Write([]byte(signedPayload))
-    expectedSig := base64.StdEncoding.EncodeToString(mac.Sum(nil))
-    
-    parts := strings.Split(signature, ",")
-    if len(parts) < 2 {
-        return false
-    }
-    
-    return hmac.Equal([]byte(expectedSig), []byte(parts[1]))
-}
+1. Go to **Developer → Webhooks → [your endpoint] → Testing**
+2. Select an event type
+3. Click **Send Example**
+4. Verify your endpoint returns `200` and the signature verifies
 
-func webhookHandler(w http.ResponseWriter, r *http.Request) {
-    body, _ := io.ReadAll(r.Body)
-    signature := r.Header.Get("webhook-signature")
-    timestamp := r.Header.Get("webhook-timestamp")
-    
-    if !verifySignature(body, signature, timestamp) {
-        http.Error(w, "Invalid signature", http.StatusUnauthorized)
-        return
-    }
-    
-    // Check timestamp
-    ts, _ := strconv.ParseInt(timestamp, 10, 64)
-    if time.Since(time.Unix(ts, 0)) > 5*time.Minute {
-        http.Error(w, "Timestamp too old", http.StatusUnauthorized)
-        return
-    }
-    
-    var event map[string]interface{}
-    json.Unmarshal(body, &event)
-    
-    switch event["type"] {
-    case "payment.succeeded":
-        handlePaymentSucceeded(event["data"].(map[string]interface{}))
-    case "subscription.active":
-        handleSubscriptionActive(event["data"].(map[string]interface{}))
-    }
-    
-    w.Header().Set("Content-Type", "application/json")
-    json.NewEncoder(w).Encode(map[string]bool{"received": true})
-}
+### CLI: Live forwarding
+
+Forward real test-mode events to localhost:
+
+```bash
+dodo wh listen http://localhost:3000/webhook
+```
+
+This creates a test webhook, opens a WebSocket relay, and forwards events with valid signatures to your local URL. Requires a test-mode API key. The URL argument is required in direct mode — bare `dodo wh listen` only works as `/wh listen` inside the TUI.
+
+### CLI: Unsigned mock events
+
+Generate realistic unsigned payloads for testing without signature verification:
+
+```bash
+dodo wh trigger payment.success http://localhost:3000/webhook
+```
+
+Use `unsafeUnwrap()` only for these unsigned payloads. Both arguments are required in direct mode.
+
+### Tunnel
+
+Expose localhost with ngrok and register the HTTPS URL in the dashboard:
+
+```bash
+ngrok http 3000
+# Register https://xxxx.ngrok.io/webhook in the dashboard
 ```
 
 ---
 
-## Best Practices
+## Common Mistakes
 
-### 1. Always Verify Signatures
-Never process webhooks without signature verification to prevent spoofing.
+### 1. Signing only the payload or `timestamp.payload`
 
-### 2. Implement Idempotency
-Use `webhook-id` header to prevent duplicate processing:
+**Wrong:**
 ```typescript
-const processedIds = new Set<string>();
+const signed = crypto.createHmac('sha256', secret)
+  .update(payload)
+  .digest('base64');
+
+// or
+const signed = crypto.createHmac('sha256', secret)
+  .update(`${timestamp}.${payload}`)
+  .digest('base64');
+```
 
-if (processedIds.has(webhookId)) {
-  return NextResponse.json({ received: true }); // Already processed
-}
-processedIds.add(webhookId);
+**Correct:** The signed message is `webhook-id.webhook-timestamp.raw_body`, all three parts joined by periods. Use the SDK helper to avoid this entirely.
+
+### 2. Re-serializing the parsed body
+
+**Wrong:**
+```typescript
+const body = await req.json();
+const signed = JSON.stringify(body); // Reordered, reformatted, breaks signature
+```
+
+**Correct:** Always use the raw bytes:
+```typescript
+const body = await req.text(); // or req.body.toString() in Express
+// Pass body directly to unwrap() or webhook.verify()
 ```
 
-### 3. Respond Quickly
-Return 200 immediately, process asynchronously if needed:
+### 3. Naive comma-splitting of the signature header
+
+**Wrong:**
 ```typescript
-// Queue for async processing
-await queue.add('process-webhook', event);
-return NextResponse.json({ received: true });
+const sig = signature.split(',')[1]; // Assumes exactly one comma
 ```
 
-### 4. Handle Retries
-Dodo Payments retries failed webhooks. Design handlers to be idempotent.
+The header is versioned and can contain multiple values. Use the SDK helper.
+
+### 4. `timingSafeEqual` throwing on length mismatch
 
-### 5. Log Everything
-Keep detailed logs for debugging:
+**Wrong:**
 ```typescript
-console.log(`[Webhook] ${event.type} - ${webhookId}`, {
-  timestamp: event.timestamp,
-  data: event.data
+crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
+// Throws if lengths differ; doesn't return false
+```
+
+**Correct:** Use the SDK helper, which handles this safely.
+
+### 5. Granting access from `return_url` instead of verified webhooks
+
+**Wrong:**
+```typescript
+// User visits return_url after checkout; you grant access
+app.get('/checkout/return', (req, res) => {
+  grantAccess(req.query.customer_id); // Unverified!
 });
 ```
 
----
+**Correct:** Grant access only after receiving and verifying a webhook:
+```typescript
+const event = client.webhooks.unwrap(rawBody, { headers });
+
+if (event.type === 'payment.succeeded') {
+  grantAccess(event.data.customer.customer_id);
+}
+```
 
-## Local Development
+### 6. Doing slow work before responding 2xx
 
-### Using ngrok
-```bash
-# Start ngrok tunnel
-ngrok http 3000
+**Wrong:**
+```typescript
+app.post('/webhook', async (req, res) => {
+  const unwrapped = client.webhooks.unwrap(...);
+  
+  // Slow database writes, email sends, etc.
+  await db.payment.create(...);
+  await sendEmail(...);
+  
+  res.json({ received: true }); // Dodo times out after 15s
+});
+```
 
-# Use the ngrok URL as your webhook endpoint
-# https://xxxx.ngrok.io/api/webhooks/dodo
+**Correct:** Durably enqueue first, then respond immediately. Return non-`2xx` if persistence fails so Dodo retries:
+```typescript
+app.post('/webhook', async (req, res) => {
+  const unwrapped = client.webhooks.unwrap(...);
+
+  try {
+    await queue.add('process-event', unwrapped); // Durable write
+    return res.json({ received: true });
+  } catch (error) {
+    console.error('Failed to persist webhook', error);
+    return res.status(503).json({ error: 'Webhook persistence failed' });
+  }
+});
 ```
 
-### Testing Webhooks
-You can trigger test webhooks from the Dodo Payments dashboard:
-1. Go to Developer → Webhooks
-2. Select your webhook
-3. Click "Send Test Event"
+### 7. Acknowledging before durable persistence
 
----
+**Wrong:**
+```typescript
+res.json({ received: true });
+await queue.add('process-event', unwrapped); // A crash can lose an acknowledged event
+```
+
+**Correct:** Verify the signature, durably insert or enqueue the event, and only then return `2xx`. If persistence fails, return non-`2xx` so Dodo retries.
 
-## Troubleshooting
+### 8. Committing an idempotency claim before fulfillment
+
+**Wrong:**
+```typescript
+const claim = await db.webhookLog.createMany({
+  data: [{ webhookId }],
+  skipDuplicates: true,
+});
+if (claim.count === 0) return;
+
+await grantSubscriptionEntitlements(event.data); // A failure leaves the claim behind
+```
 
-### Signature Verification Failing
-- Ensure you're using the raw request body
-- Check webhook secret is correct
-- Verify timestamp format (Unix seconds)
+The retry sees the existing claim and skips fulfillment, permanently dropping the event.
 
-### Not Receiving Webhooks
-- Check endpoint is publicly accessible
-- Verify webhook is enabled in dashboard
-- Check server logs for errors
+**Correct:** Commit the claim and all durable fulfillment changes in one transaction. A failure rolls both back, so the retry can claim the event again:
+```typescript
+const event = client.webhooks.unwrap(rawBody, { headers });
+
+await db.$transaction(async (tx) => {
+  const claim = await tx.webhookLog.createMany({
+    data: [{ webhookId, eventType: event.type }],
+    skipDuplicates: true,
+  });
+  if (claim.count === 0) return;
+
+  if (event.type === 'subscription.active') {
+    await grantSubscriptionEntitlements(event.data, tx);
+  }
+});
+```
 
-### Duplicate Events
-- Implement idempotency using webhook-id
-- Store processed event IDs in database
+Use a transactional outbox for email or other external effects that must follow the database commit.
 
 ---
 
 ## Resources
 
 - [Webhook Documentation](https://docs.dodopayments.com/developer-resources/webhooks)
-- [Event Reference](https://docs.dodopayments.com/developer-resources/webhooks/intents/webhook-events-guide)
+- [Event Catalog](https://docs.dodopayments.com/developer-resources/webhooks/intents/webhook-events-guide)
 - [Standard Webhooks Spec](https://standardwebhooks.com/)
-- [Credit Webhook Events](https://docs.dodopayments.com/developer-resources/webhooks/intents/credit)
+- [Framework Adaptors](https://docs.dodopayments.com/developer-resources/framework-adaptors)
+- [CLI Reference](https://docs.dodopayments.com/developer-resources/sdks/cli)