@puntoycoma/paddlehook

Typed Paddle webhook verification for any edge runtime — HMAC-SHA256 signatures, replay protection, and fully typed events in 3.34 KB with zero runtime dependencies.

Why paddlehook?

• Secure — HMAC-SHA256 signature verification via crypto.subtle.verify() (Web Crypto API, constant-time comparison) with built-in replay attack protection
• Typed events — Discriminated union of all Paddle billing event types; TypeScript narrows event.data automatically per event
• Tiny — 3.34 KB minified, zero runtime dependencies, no supply chain risk
• Universal — Works on Cloudflare Workers, Supabase Edge Functions, Deno, Bun, Vercel Edge, Netlify Edge, Hono, and Node.js 18+
• Flexible — Proxy mode for instant setup; onVerified callback for queues, databases, or any custom Paddle payments processing
• Filterable — Pass an events array to ignore event types your app doesn't care about

Architecture

Paddle billing platform
        │
        │  POST /webhook
        │  Paddle-Signature: ts=…;h1=…
        ▼
┌────────────────────┐
│    paddlehook      │  ← HMAC-SHA256 verify + replay check
│                    │
│  proxy mode        │  → forwards raw body to TARGET_URL
│  onVerified mode   │  → calls your handler with typed PaddleWebhookEvent
└────────────────────┘
        │
        ▼
  Your backend / queue / database

Install

npm install @puntoycoma/paddlehook
# or
bun add @puntoycoma/paddlehook
# or
pnpm add @puntoycoma/paddlehook

Quick Start

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

export default {
  fetch: createPaddleWebhookHandler(),
}

Set three environment variables and Paddle webhook verification is live:

| Variable | Description | |----------|-------------| | PADDLE_WEBHOOK_SECRET | Signing secret from Paddle Dashboard > Developer Tools > Notifications | | TARGET_URL | Your backend endpoint (e.g. https://api.example.com/webhooks/paddle) | | INTERNAL_AUTH_TOKEN | Your secret token (plain, without Bearer prefix). Sent to your backend as Authorization: Bearer <token> automatically. |

Two Modes

Proxy mode (default)

Verifies the Paddle webhook signature, then forwards the raw body to your backend with a Bearer token. Your backend receives the same JSON Paddle sent — no transformation.

Use proxy mode when your backend already handles Paddle event logic and you just need a verified relay at the edge.

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

// Requires: PADDLE_WEBHOOK_SECRET, TARGET_URL, INTERNAL_AUTH_TOKEN
export default {
  fetch: createPaddleWebhookHandler(),
}

Custom mode (onVerified)

Verifies the signature, parses the payload into a typed PaddleWebhookEvent, then calls your function. You own the response — enqueue, store, process inline, anything.

Use custom mode when you want to react to Paddle payments events directly at the edge: push to a queue, write to a database, or run conditional logic based on event type.

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

// Only requires: PADDLE_WEBHOOK_SECRET
const handler = createPaddleWebhookHandler({
  onVerified: (event, env) => {
    // event is a fully typed PaddleWebhookEvent — no JSON.parse needed
    console.log(event.event_type, event.data)
    return new Response(null, { status: 202 })
  },
})

export default { fetch: handler }

Typed Events

PaddleWebhookEvent is a discriminated union — TypeScript narrows event.data automatically when you check event.event_type.

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"
import type { PaddleWebhookEvent, SubscriptionData, TransactionData } from "@puntoycoma/paddlehook"

const handler = createPaddleWebhookHandler({
  onVerified: (event) => {
    switch (event.event_type) {
      case "subscription.activated":
      case "subscription.canceled":
      case "subscription.updated": {
        // event.data is SubscriptionData here
        const sub = event.data as SubscriptionData
        console.log(sub.id, sub.status, sub.customer_id)
        break
      }

      case "transaction.completed":
      case "transaction.paid": {
        // event.data is TransactionData here
        const tx = event.data as TransactionData
        console.log(tx.id, tx.status, tx.customer_id)
        break
      }

      default: {
        // All other Paddle billing events — log and acknowledge
        console.log("unhandled event:", event.event_type)
      }
    }

    return new Response(null, { status: 200 })
  },
})

Filter to specific events

Use the events option to tell paddlehook which Paddle event types to process. Other event types receive a 200 { ok: true, skipped: true } response immediately — no work done, Paddle stays happy.

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

const handler = createPaddleWebhookHandler({
  events: ["subscription.activated", "subscription.canceled", "transaction.completed"],
  onVerified: (event) => {
    // Only called for the three event types above
    return new Response(null, { status: 200 })
  },
})

PaddleEventType covers all documented Paddle events — your editor will autocomplete valid values.

Runtime Examples

Cloudflare Workers

The runtime injects env per request automatically — no setup beyond the handler.

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

export default {
  fetch: createPaddleWebhookHandler(),
}

Supabase Edge Functions / Deno / Netlify Edge

All Deno-based runtimes read env vars with Deno.env.get().

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

const env = {
  PADDLE_WEBHOOK_SECRET: Deno.env.get("PADDLE_WEBHOOK_SECRET")!,
  TARGET_URL: Deno.env.get("TARGET_URL")!,
  INTERNAL_AUTH_TOKEN: Deno.env.get("INTERNAL_AUTH_TOKEN")!,
}

const handler = createPaddleWebhookHandler()

Deno.serve((request) => handler(request, env))

Bun / Node.js 18+ / Vercel Edge

All process.env runtimes follow the same pattern.

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

const env = {
  PADDLE_WEBHOOK_SECRET: process.env.PADDLE_WEBHOOK_SECRET!,
  TARGET_URL: process.env.TARGET_URL!,
  INTERNAL_AUTH_TOKEN: process.env.INTERNAL_AUTH_TOKEN!,
}

const handler = createPaddleWebhookHandler()

// Bun
Bun.serve({ fetch: (req) => handler(req, env) })

// Node.js 18+
import { serve } from "@hono/node-server" // or any http adapter
serve({ fetch: (req) => handler(req, env) })

// Vercel Edge
export default (req: Request) => handler(req, env)
export const config = { runtime: "edge" }

Hono (any runtime)

Hono runs on Cloudflare Workers, Deno, Bun, Node.js — anywhere Hono runs, paddlehook works.

import { Hono } from "hono"
import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

const app = new Hono()
const handler = createPaddleWebhookHandler()

app.post("/webhook/paddle", (c) =>
  handler(c.req.raw, {
    PADDLE_WEBHOOK_SECRET: c.env.PADDLE_WEBHOOK_SECRET,
    TARGET_URL: c.env.TARGET_URL,
    INTERNAL_AUTH_TOKEN: c.env.INTERNAL_AUTH_TOKEN,
  })
)

export default app

Using onVerified

Enqueue to a queue system

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

// Cloudflare Queue — env is typed to include the binding
const handler = createPaddleWebhookHandler<Env>({
  onVerified: (event, env) => {
    // event is already parsed — send it directly to the queue
    env.PADDLE_QUEUE.send(event)
    return new Response(null, { status: 202 })
  },
})

// Same pattern for AWS SQS, Redis, BullMQ, Upstash, etc.
// Verification happens first; your callback only runs on valid Paddle payloads.

Custom event processing

import { createPaddleWebhookHandler } from "@puntoycoma/paddlehook"

const handler = createPaddleWebhookHandler({
  events: ["subscription.canceled", "subscription.updated"],
  onVerified: async (event, env) => {
    // No JSON.parse needed — event is already a typed PaddleWebhookEvent
    if (event.event_type === "subscription.canceled") {
      await db.subscriptions.update({
        where: { paddleId: event.data.id },
        data: { status: "canceled" },
      })
    }

    return new Response(null, { status: 200 })
  },
})

Low-level: verifyPaddleSignature

Use the verification function directly if you manage your own request lifecycle.

import { verifyPaddleSignature } from "@puntoycoma/paddlehook"

const isValid = await verifyPaddleSignature(
  request.headers.get("paddle-signature"),
  await request.text(),
  env.PADDLE_WEBHOOK_SECRET,
  { maxAge: 300 } // optional — default 300s, set 0 to disable replay protection
)

if (!isValid) {
  return new Response("Unauthorized", { status: 401 })
}

Response Mapping (proxy mode)

| Backend response | paddlehook returns | Paddle behavior | |------------------|--------------------|-----------------| | 2xx | 200 | Success, no retry | | 4xx | 400 | Client error, no retry | | 5xx | 500 | Server error, Paddle retries | | Unreachable | 502 | Gateway error, Paddle retries |

API Reference

createPaddleWebhookHandler(options?)

Factory that creates a Paddle webhook handler for any edge runtime. Verifies HMAC-SHA256 signatures and either proxies the payload to your backend or calls your onVerified callback.

const handler = createPaddleWebhookHandler<TEnv>(options?)
// Returns: (request: Request, env: TEnv) => Promise<Response>

| Parameter | Type | Description | |-----------|------|-------------| | options.events | PaddleEventType[] | Optional. Only call onVerified for these event types. Others receive 200 { ok: true, skipped: true }. | | options.onVerified | (event: PaddleWebhookEvent, env: TEnv) => Response \| Promise<Response> | Optional. Custom handler called after successful verification. Omit to use proxy mode. |

verifyPaddleSignature(header, rawBody, secret, options?)

Low-level Paddle webhook HMAC-SHA256 signature verification using the Web Crypto API.

| Parameter | Type | Description | |-----------|------|-------------| | header | string \| null | Paddle-Signature header value | | rawBody | string | Raw request body (unparsed string) | | secret | string | Paddle webhook signing secret | | options.maxAge | number | Max signature age in seconds. Default 300. Set 0 to disable replay protection. |

Returns Promise<boolean>.

Types

// Environment shapes
interface PaddleBaseEnv {
  PADDLE_WEBHOOK_SECRET: string
}

interface PaddleWorkerEnv extends PaddleBaseEnv {
  TARGET_URL: string
  INTERNAL_AUTH_TOKEN: string
}

// Handler options
interface HandlerOptions<TEnv extends PaddleBaseEnv> {
  events?: PaddleEventType[]
  onVerified?: (event: PaddleWebhookEvent, env: TEnv) => Response | Promise<Response>
}

// Verify options
interface VerifyOptions {
  maxAge?: number
}

// Event envelope — discriminated union on event_type
type PaddleWebhookEvent =
  | PaddleEvent<"subscription.activated", SubscriptionData>
  | PaddleEvent<"subscription.canceled", SubscriptionData>
  | PaddleEvent<"subscription.created", SubscriptionData>
  | PaddleEvent<"subscription.updated", SubscriptionData>
  | PaddleEvent<"transaction.completed", TransactionData>
  | PaddleEvent<"transaction.paid", TransactionData>
  | PaddleEvent<"customer.created", CustomerData>
  | PaddleEvent<"adjustment.created", AdjustmentData>
  // ... all Paddle billing event types

// Available data types
// SubscriptionData, TransactionData, CustomerData, AdjustmentData

All types are exported from @puntoycoma/paddlehook.

Security

• HMAC-SHA256 verification via crypto.subtle.verify() — constant-time comparison, no timing attacks
• Replay protection — rejects signatures older than 5 minutes by default (configurable via maxAge)
• Method guard — non-POST requests are rejected with 405 before any processing
• Zero runtime dependencies — no third-party code executes in your edge function
• npm provenance — published with attestation for verifiable, auditable builds

License

MIT — free to use, modify, and distribute. See LICENSE for details.

Contributing

Issues and PRs welcome at github.com/PuntoyComaTech/paddlehook.

bun install     # install dependencies
bun test        # run tests
bun run build   # build for production

Developed by PuntoyComaTech

A lightweight, type-safe Paddle webhook handler for edge runtimes.