Webhooks

Receive payment, membership, and event notifications from Whop in realtime.

A webhook is a POST request that Whop sends to your server when an event occurs. Examples of events: a payment succeeds, a membership activates, a dispute opens. You register a public URL. Whop sends a signed JSON event to this URL each time one of your subscribed events occurs.

Whop webhooks use the Standard Webhooks specification. The Whop SDKs verify the signature and parse the event in one call.

What a webhook looks like

Each event is one POST request:

POST /webhooks/whop HTTP/1.1
content-type: application/json
webhook-id: msg_bQPHmO2eBnHYtWWuxAN9K3Xd
webhook-timestamp: 1786381404
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pCPljWFR61G0P0=

{
  "id": "msg_bQPHmO2eBnHYtWWuxAN9K3Xd",
  "type": "payment.succeeded",
  "api_version": "v1",
  "api_version_date": "2026-08-14",
  "timestamp": "2026-08-10T17:03:24.291Z",
  "account_id": "biz_XXXXXXXX",
  "data": {
    "id": "pay_XXXXXXXX",
    "...": "the full payment object"
  }
}

The envelope follows your webhook’s api_version_date pin, the same way data does. Webhooks pinned before 2026-08-14 — and webhooks without a pin — receive the account field as company_id instead of account_id.

The HTTP request headers version the same way: any future header change ships as a dated API version, and your pin keeps the headers you integrated against. Four headers are contractually frozen and never change on any version: webhook-id, webhook-signature, webhook-timestamp, and content-type — signature verification works identically on every pin.

One optional envelope field describes what changed:

• previous_attributes — present on .updated events that capture changes (account.updated, product.updated, plan.updated, and shipment.updated): an object with the old values of the data fields that changed, keyed by field name. Renaming the account to “Shine Time Auto Detailing” delivers {"title": "Webb's Mobile Detailing"} — the value each changed field had before the write. When the field is absent, no change capture was available for the event. Values follow your webhook’s api_version_date pin, the same way data does.

Create a webhook

API

curl -X POST "https://api.whop.com/api/v1/webhooks" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/whop",
    "events": ["payment.succeeded"]
  }'

The response contains webhook_secret. The API shows this value only one time. Store it immediately. See the Webhooks API reference for all fields, including resource_id (the company or app that owns the webhook) and child_resource_events.

Dashboard

1. Open the Developer tab of your dashboard and select Create webhook.
2. Enter your endpoint URL and select the events.
3. After you create the webhook, copy the signing secret from the Secret column of the table. Store it as WHOP_WEBHOOK_SECRET.

Verify and handle events

Always verify the signature before you use a payload.

1. Set up your SDK client

   Give the secret to the SDK client when you construct it:

   Typescript

   import { Whop } from "@whop/sdk";
   
   export const whopsdk = new Whop({
      	apiKey: process.env.WHOP_API_KEY,
      	webhookKey: btoa(process.env.WHOP_WEBHOOK_SECRET || ""),
   });
   
2. Handle events on your server

   One call verifies the signature and parses the event. If the signature isn’t correct, the call throws an error. Your handler doesn’t receive payloads that failed verification.

   Typescript + NextJS

   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> {
      	// Verify and parse. Give the raw body. If you parse the body first, the signature check fails.
      	const requestBodyText = await request.text();
      	const headers = Object.fromEntries(request.headers);
      	const event = whopsdk.webhooks.unwrap(requestBodyText, { headers });
   
      	if (event.type === "payment.succeeded") {
     		waitUntil(handlePaymentSucceeded(event.data));
      	}
   
      	// Respond in less than 5 seconds, or Whop retries.
      	return new Response("OK", { status: 200 });
   }
   
   async function handlePaymentSucceeded(payment: Payment) {
      	// Do the fulfillment work here: update your database, give access, send email.
      	console.log("[PAYMENT SUCCEEDED]", payment);
   }
   

   Do only the necessary work before you respond: verify the event, put the work in a queue, and return 200. The TypeScript example uses waitUntil from @vercel/functions. On other runtimes, use the background-task function of your framework or a job queue.

Verify without an SDK

Whop signs the string {webhook-id}.{webhook-timestamp}.{raw body} with HMAC-SHA256. The key is your ws_... secret. The webhook-signature header contains the result in base64: v1,<signature>.

To verify a request: compute the HMAC over the raw request body, encode the result in base64, and compare it to the header value with a constant-time comparison. Reject a request if its webhook-timestamp is more than 5 minutes from the current time. This prevents replay attacks. The SDK verifiers apply this limit automatically.

Test your endpoint

• Send a test event. In the dashboard, open the menu of the webhook and select a test event. Or call POST /api/v1/webhooks/{id}/test. Whop sends a sample payload to your URL and returns the response status and body from your server.
• Examine deliveries. Whop keeps each delivery for 30 days: the request, the response code, the response body, and the timing. See the deliveries in the dashboard or with GET /api/v1/webhooks/{id}/deliveries.

A webhook URL must be reachable from the public internet. Whop rejects localhost and private-network addresses. For local development, use ngrok or Cloudflare Tunnel to forward a public URL to your machine. Register the tunnel URL.

Delivery

Respond with a 2xx status in less than 5 seconds. All other results are failed attempts: a timeout, an error status, or a redirect. Whop doesn’t follow redirects.

Whop delivers each event at least one time. The same event can arrive more than one time. Make your handler idempotent. Each retry of a delivery has the same webhook-id. Store the webhook-id and ignore duplicates.

Whop retries failed deliveries for approximately 3 days. After the first attempt, Whop retries 12 times with increased delays: 30 seconds, 2 minutes, 8 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, and then each 12 hours. The full schedule is approximately 71 hours.

The sequence of deliveries isn’t guaranteed. A newer event can arrive before an older event. Process each event independently. If the sequence is important, read the current state from the API.

Whop disables endpoints that continue to fail. If all deliveries to your endpoint fail for 24 hours, Whop sends a warning email to your company. If the failures continue for 72 hours and 10 or more deliveries failed, Whop disables the webhook and sends a second email. To enable the webhook again, use the dashboard or send PATCH /api/v1/webhooks/{id} with "enabled": true. This resets the failure history. Whop doesn’t send the events that occurred while the webhook was turned off. Read the API to find the data that you missed.

Troubleshoot webhook delivery

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

Events and versions

Two version fields control the data that your endpoint receives:

• api_version — the envelope format. Use v1. This page describes only v1. The legacy formats v2 and v5 exist for old integrations and don’t use Standard Webhooks signatures. Don’t use them for new integrations.
• api_version_date — the dated API version that sets the shape of data and of the envelope itself (for example, pins from 2026-08-14 carry account_id where older pins carry company_id). It operates the same as the Api-Version-Date header on REST reads. Set it when you create a webhook with the API. Then the payload shape stays stable when the API changes. Webhooks without a pin keep their initial payload and envelope shape. Exception: resources that exist only on the current API (cards, plans, transfers, swaps, deposits, exports) always receive the latest data shape — the envelope still follows the pin.

Event names have the format resource.action. Each event in the table links to a reference page with the payload schema:

Resource	Events
Accounts	account.updated
Ad Campaigns	ad_campaign.payment_failed
Card transactions	card_transaction.completed, card_transaction.created, card_transaction.declined, card_transaction.reversed, card_transaction.updated
Cards	card.canceled, card.created, card.frozen, card.updated, card_application.approved, card_application.created, card_application.denied, card_application.updated
Course lesson interactions	course_lesson_interaction.completed
Deposits	deposit.succeeded
Dispute alerts	dispute_alert.created
Disputes	dispute.created, dispute.updated
Entries	entry.approved, entry.created, entry.deleted, entry.denied
Exports	export.completed, export.failed
Identity profiles	identity_profile.updated
Invoices	invoice.created, invoice.marked_uncollectible, invoice.paid, invoice.past_due, invoice.voided
Ledger accounts	ledger_account.funds_available
Members	member.created
Memberships	membership.activated, membership.cancel_at_period_end_changed, membership.deactivated, membership.trial_ending_soon
Messages	chat.message.created
Payments	payment.created, payment.failed, payment.pending, payment.succeeded
Payout accounts	payout_account.status_updated
Payout methods	payout_method.created
Plans	plan.created, plan.deleted, plan.updated
Products	product.created, product.deleted, product.published, product.unpublished, product.updated
Reactions	chat.reaction.created
Refunds	refund.created, refund.updated
Resolution center cases	resolution_center_case.created, resolution_center_case.decided, resolution_center_case.updated
Setup intents	setup_intent.canceled, setup_intent.requires_action, setup_intent.succeeded
Shipments	shipment.created, shipment.updated
Swaps	swap.completed
Transfers	transfer.completed, transfer.created, transfer.failed
Verifications	verification.succeeded
Withdrawals	withdrawal.created, withdrawal.reversed, withdrawal.updated

Next steps

Accept payments

Use payment.succeeded webhooks with checkout to fulfill orders.

Save payment methods

Use setup intents and webhooks to charge customers later.

API walkthrough

See how webhooks operate with checkout, transfers, and KYC.

Webhooks API reference

All endpoints and fields: create, update, test, deliveries.