Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.whop.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks are POST requests from Whop to your server. Use them to react to events like payment.succeeded, membership.activated, or entry.created.
Webhooks follow the Standard Webhooks spec. Our SDKs handle unwrapping and signature verification for you.

​
Set up a webhook

1

Create the webhook in the dashboard

Navigate to the Developer tab in your dashboard.Click Create Webhook in the top right corner.
2

Choose events and URL

Enter your webhook URL and select the events that you want to receive. Ensure that you are on API version v1.
When testing locally, use ngrok or Cloudflare Tunnel to forward requests to your local development environment.
3

Store the webhook secret

Copy the webhook secret from the dashboard and store it as WHOP_WEBHOOK_SECRET.
4

Handle events on your server

Your endpoint now receives POST requests for every event you selected. See Validating webhooks for example handlers.

​
Validating webhooks

Always verify webhook signatures before you trust the payload. Otherwise someone could send your endpoint a fake event.
1

Set up your SDK client

Pass the secret into the SDK client on construction:
import { Whop } from "@whop/sdk";

export const whopsdk = new Whop({
   	apiKey: process.env.WHOP_API_KEY,
   	webhookKey: btoa(process.env.WHOP_WEBHOOK_SECRET || ""),
});
2

Set up your API handler

Create a route that accepts HTTP POST requests. Use the same URL you entered during webhook creation.
Our SDK unwraps and verifies the signature in one call. A bad signature raises; your handler won’t see tampered events.
The TypeScript example uses waitUntil from @vercel/functions to run the handler after responding 200. On other runtimes (Bun, Cloudflare Workers, Fastify, Hono) swap it for your framework’s equivalent background-task primitive, or a job queue. The Python and Ruby examples show framework-native equivalents.
import { waitUntil } from "@vercel/functions";
import type { Payment } from "@whop/sdk/resources.js";
import type { NextRequest } from "next/server";
import { whopsdk } from "@/lib/whop-sdk";

export async function POST(request: NextRequest): Promise<Response> {
   	// Validate the webhook to ensure it's from Whop
   	const requestBodyText = await request.text();
   	const headers = Object.fromEntries(request.headers);
   	const webhookData = whopsdk.webhooks.unwrap(requestBodyText, { headers });

   	// Handle the webhook event
   	if (webhookData.type === "payment.succeeded") {
  		waitUntil(handlePaymentSucceeded(webhookData.data));
   	}

   	// Make sure to return a 2xx status code quickly. Otherwise the webhook will be retried.
   	return new Response("OK", { status: 200 });
}

async function handlePaymentSucceeded(invoice: Payment) {
   	// This is a placeholder for a potentially long running operation
   	// In a real scenario, you might need to fetch user data, update a database, etc.
   	console.log("[PAYMENT SUCCEEDED]", invoice);
}

​
Delivery guarantees

  • At-least-once delivery. You may receive the same event more than once. Make your handler idempotent. Use the webhook-id header (or a unique field in the event body) as a dedup key.
  • Retries on non-2xx responses. Whop makes the initial delivery attempt, then retries up to 3 times after 10 seconds, 20 seconds, and 40 seconds if your endpoint errors or does not return a 2xx in time. Failed deliveries stop after that short retry window.
  • Ordering is not guaranteed. An event created later may arrive before an earlier one. Don’t assume sequential delivery.
  • Respond fast. Do the minimum work needed to acknowledge the event (verify + enqueue), then return 2xx. Long-running fulfillment belongs in a background task.

Troubleshoot webhook delivery

Fix signature failures, retries, duplicate events, and local tunnel issues.

​
Available webhooks

Every webhook Whop sends is documented in the API Reference. Within each resource, the hook pages specify the event name and the exact payload schema. Common events:

​
Next steps

Accept payments

Pair payment.succeeded webhooks with checkout to fulfill orders.

Save payment methods

Use setup intents + webhooks to charge customers later.

API walkthrough

See where webhooks fit alongside checkout, transfers, and KYC.

Run a local dev proxy

Forward Whop webhooks to localhost while developing.