Webhooks
Verify provider deliveries, normalize events, and sync local billing state.
Every important state transition in PayKit starts with a provider webhook. PayKit does three things in order:
- verify the provider webhook
- normalize it into one PayKit event shape
- sync local state and call your handlers
Framework handler
import { paykit } from "@/lib/paykit";
import { paykitHandler } from "paykitjs/handlers/next";
export const { GET, POST } = paykitHandler(paykit);Low-level entry
await paykit.handleWebhook({
providerId: "stripe",
body,
headers,
});Event model
const paykit = createPayKit({
// ...
on: {
"payment_method.attached": ({ customer, paymentMethod }) => {},
"payment_method.detached": ({ customer, paymentMethod }) => {},
"checkout.completed": ({ customer, providerId }) => {},
"charge.succeeded": ({ customer, charge }) => {},
"charge.failed": ({ customer, charge, error }) => {},
"charge.refunded": ({ customer, charge, refund }) => {},
"*": ({ event }) => {},
},
});The payloads use PayKit models, not raw provider payloads. That keeps handlers portable across providers.