@dodopayments/opencode-plugin 0.6.0 → 0.6.2

package/skills/webhook-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: webhook-integration
-description: Complete guide for setting up and handling Dodo Payments webhooks for real-time payment event notifications.
+description: Dodo Payments webhook handling, covering endpoint setup, Standard Webhooks signature verification on the raw body, payment, subscription, and refund event types, idempotency with webhook-id, retries, and local testing. Use when receiving Dodo events, verifying webhook-signature headers, or syncing your database from payment.succeeded or subscription events.
 ---
 
 # Dodo Payments Webhook Integration
@@ -272,91 +272,19 @@ Signature verification requires the exact bytes Dodo sent. If you parse the JSON
 
 ## 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 |
+Full guide: [references/event-catalog.md](references/event-catalog.md).
 
----
+Covers:
+
+- Payment events
+- Subscription events
+- Refund events
+- Dispute events
+- License key events
+- Entitlement grant events
+- Credit events
+- Recovery and dunning events
+- Payout events
 
 ## Production-Grade Handler Pattern
 
@@ -464,7 +392,7 @@ Understand how Dodo delivers webhooks:
 
 | Property | Behavior |
 |----------|----------|
-| **Timeout** | 15 seconds for connection and read |
+| **Timeout** | 30 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 |
@@ -483,7 +411,7 @@ If you use a supported framework, use the official adaptor package for built-in
 |-----------|---------|---|
 | Next.js | `@dodopayments/nextjs` | `Webhooks({ webhookKey, onPayload })` |
 | Nuxt | `@dodopayments/nuxt` | `Webhooks({ webhookKey, onPayload })` |
-| Express | `@dodopayments/express` | Middleware with raw-body parser |
+| Express | `@dodopayments/express` | `Webhooks({ webhookKey, onPayload })` - register `express.json()` first, **not** `express.raw()` (it verifies against the parsed `req.body`) |
 | Fastify | `@dodopayments/fastify` | `Webhooks({ webhookKey, onPayload })` |
 | Hono | `@dodopayments/hono` | `Webhooks({ webhookKey, onPayload })` |
 | Astro | `@dodopayments/astro` | `Webhooks({ webhookKey, onPayload })` |
@@ -534,189 +462,29 @@ Handle `subscription.active` only in a handler that exposes `webhook-id`, then c
 
 ## Local Testing
 
-### Dashboard test tool
-
-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
-
-### 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.
+Full guide: [references/local-testing.md](references/local-testing.md).
 
-### CLI: Unsigned mock events
+Covers:
 
-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
-```
-
----
+- Dashboard test tool
+- CLI: Live forwarding
+- CLI: Unsigned mock events
+- Tunnel
 
 ## Common Mistakes
 
-### 1. Signing only the payload or `timestamp.payload`
-
-**Wrong:**
-```typescript
-const signed = crypto.createHmac('sha256', secret)
-  .update(payload)
-  .digest('base64');
-
-// or
-const signed = crypto.createHmac('sha256', secret)
-  .update(`${timestamp}.${payload}`)
-  .digest('base64');
-```
-
-**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. Naive comma-splitting of the signature header
-
-**Wrong:**
-```typescript
-const sig = signature.split(',')[1]; // Assumes exactly one comma
-```
+Full guide: [references/common-mistakes.md](references/common-mistakes.md).
 
-The header is versioned and can contain multiple values. Use the SDK helper.
+Covers:
 
-### 4. `timingSafeEqual` throwing on length mismatch
-
-**Wrong:**
-```typescript
-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);
-}
-```
-
-### 6. Doing slow work before responding 2xx
-
-**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
-});
-```
-
-**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' });
-  }
-});
-```
-
-### 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.
-
-### 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
-```
-
-The retry sees the existing claim and skips fulfillment, permanently dropping the event.
-
-**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);
-  }
-});
-```
-
-Use a transactional outbox for email or other external effects that must follow the database commit.
-
----
+- Signing anything other than `webhook-id.webhook-timestamp.raw_body`
+- Re-serializing the parsed body
+- Naive comma-splitting of the signature header
+- `timingSafeEqual` throwing on length mismatch
+- Granting access from `return_url` instead of verified webhooks
+- Doing slow work before responding 2xx
+- Acknowledging before durable persistence
+- Committing an idempotency claim before fulfillment
 
 ## Resources
 

package/skills/webhook-integration/references/common-mistakes.md

@@ -0,0 +1,146 @@
+# Dodo Payments Webhook Integration: Common Mistakes
+
+
+### 1. Signing only the payload or `timestamp.payload`
+
+**Wrong:**
+```typescript
+const signed = crypto.createHmac('sha256', secret)
+  .update(payload)
+  .digest('base64');
+
+// or
+const signed = crypto.createHmac('sha256', secret)
+  .update(`${timestamp}.${payload}`)
+  .digest('base64');
+```
+
+**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. Naive comma-splitting of the signature header
+
+**Wrong:**
+```typescript
+const sig = signature.split(',')[1]; // Assumes exactly one comma
+```
+
+The header is versioned and can contain multiple values. Use the SDK helper.
+
+### 4. `timingSafeEqual` throwing on length mismatch
+
+**Wrong:**
+```typescript
+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);
+}
+```
+
+### 6. Doing slow work before responding 2xx
+
+**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 30s
+});
+```
+
+**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' });
+  }
+});
+```
+
+### 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.
+
+### 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
+```
+
+The retry sees the existing claim and skips fulfillment, permanently dropping the event.
+
+**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);
+  }
+});
+```
+
+Use a transactional outbox for email or other external effects that must follow the database commit.
+
+---

package/skills/webhook-integration/references/event-catalog.md

@@ -0,0 +1,103 @@
+# Dodo Payments Webhook Integration: Webhook Event Catalog
+
+
+Dodo delivers 48 event types across ten families (payment, subscription, refund, dispute, license key, entitlement grant, credit, abandoned checkout, dunning, payout). 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.past_due` | Renewal failed and the grace period opened; customer keeps access (payload has `past_due_ends_at`) | Prompt for payment before the deadline |
+| `subscription.on_hold` | Failed renewal stops renewals and revokes access | Notify customer, prompt payment method update |
+| `subscription.paused` | Subscription is deliberately paused | Suspend access while paused |
+| `subscription.unpaused` | Paused subscription is resumed | Restore access |
+| `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 | Legacy; prefer `entitlement_grant.created` with `status: "Delivered"` |
+
+### Entitlement grant events
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `entitlement_grant.created` | Grant row is created. Auto-fulfilled license keys arrive here with `status: "Delivered"` and a `license_key`; no `.delivered` follows | Grant access when `status` is `Delivered`; otherwise prepare for fulfillment |
+| `entitlement_grant.delivered` | An existing grant moves to `Delivered` (manual fulfillment, or a revoked grant restored) | 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 |
+
+### Payout events
+
+These concern your own funds moving to your bank account - use them for bookkeeping, not customer access.
+
+| Event | When it fires | What to do |
+|-------|---|---|
+| `payout.created` | Payout is created (formerly emitted as `payout.not_initiated`) | Record the pending payout |
+| `payout.in_progress` | Payout processing starts | Mark as in transit |
+| `payout.on_hold` | Payout is paused or under review | Check whether more information is required |
+| `payout.success` | Payout settles to your bank account | Reconcile in accounting |
+| `payout.failed` | Payout fails; amount and fees return to your wallet | Alert finance, check bank details |
+
+---

package/skills/webhook-integration/references/local-testing.md

@@ -0,0 +1,42 @@
+# Dodo Payments Webhook Integration: Local Testing
+
+
+### Dashboard test tool
+
+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
+
+### 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 the original `webhook-id`/`webhook-signature`/`webhook-timestamp` headers to your local URL. Requires a test-mode API key. The relay and CLI parse and **re-serialize** the JSON body, so if it differs byte-for-byte from the original (for example number formatting), signature verification fails even though the headers are intact - that is a relay artifact, not a bug in your verifier. 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.
+
+Trigger names are not always the payload `type`: `payment.success` sends `type: "payment.succeeded"`, `refund.success` sends `refund.succeeded`, and `licence.created` sends `license_key.created`. Your handler must switch on the payload types. `subscription.past_due` and `subscription.unpaused` cannot be triggered.
+
+### 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
+```
+
+---