Skip to main content
En webhook er en POST-request, som Whop sender til din server, når en hændelse indtræffer. Eksempler på hændelser: en betaling gennemføres, et medlemskab aktiveres, en tvist åbnes. Du registrerer en offentlig URL. Whop sender en signeret JSON-hændelse til denne URL, hver gang en af de hændelser, du abonnerer på, indtræffer.
Whop-webhooks bruger specifikationen Standard Webhooks. Whop-SDK’erne verificerer signaturen og parser hændelsen i ét kald. Til Go skal du bruge Verificer uden et SDK nederst på denne side.

Sådan ser en webhook ud

Hver hændelse er én POST-request:
Konvolutten følger din webhooks fastlåste api_version_date på samme måde som data. Webhooks, der er fastlåst før 2026-08-14 — og webhooks uden fastlåsning — modtager kontofeltet som company_id i stedet for account_id. HTTP-requestens headers versioneres på samme måde: enhver fremtidig ændring af headers udgives som en dateret API-version, og din fastlåsning bevarer de headers, du har integreret mod. Fire headers er kontraktligt låst og ændres aldrig i nogen version: webhook-id, webhook-signature, webhook-timestamp og content-type — signaturverifikation fungerer identisk for alle fastlåsninger. Ét valgfrit felt i konvolutten beskriver, hvad der er ændret:
  • previous_attributes — findes på .updated-hændelser, der registrerer ændringer (account.updated, product.updated, plan.updated og shipment.updated): et objekt med de gamle værdier for de data-felter, der er ændret, med feltnavnet som nøgle. Omdøbes kontoen til “Shine Time Auto Detailing”, leveres {"title": "Webb's Mobile Detailing"} — den værdi, hvert ændret felt havde før skrivningen. Når feltet mangler, var der ingen registrering af ændringer tilgængelig for hændelsen. Værdierne følger din webhooks fastlåste api_version_date på samme måde som data.

Genopret en abonnementsbetaling

Når banken beder køberen om at verificere en off-session-opkrævning, udsender Whop payment.requires_action. Send dens data.recovery_url til køberen, så vedkommende kan logge ind på Whop og gennemføre 3D Secure for den betaling. On-session-checkouts udsender den aldrig, fordi køberen allerede er i gang med udfordringen. En mislykket abonnementsfornyelse udsender også payment.failed. Se data.decline_code og data.failure_message for årsagen, når den er tilgængelig, og brug også data.recovery_url dér, når den findes. Det samme recovery_url-felt er tilgængeligt, når du henter Payment-ressourcen. Betalingslister indeholder ikke genopretningslinks. Den er null, når genopretning af godkendelse ikke er tilgængelig, eller når du mangler member:basic:read. At åbne linket starter ikke en opkrævning: køberen skal bekræfte, og Whop kontrollerer, om betalingen stadig kan genoprettes. Efter genopretning skal du fortsætte med at håndtere payment.succeeded eller payment.failed for udfaldet.

Opret en webhook

Svaret indeholder webhook_secret. API’et viser kun denne værdi én gang. Gem den med det samme. Se API-referencen for webhooks for alle felter, herunder resource_id (den konto eller app, der ejer webhooken) og child_resource_events. En webhook, der tilhører en app, modtager også appens installations- og afinstallationshændelser. Se App-installationer.

Verificer og håndter hændelser

Verificer altid signaturen, før du bruger en payload.
1

Gem din signeringshemmelighed

Verifikation kræver hemmeligheden, ikke en SDK-klient. Gem den værdi, API’et returnerede, som WHOP_WEBHOOK_SECRET, og send den til hjælpefunktionen præcis, som Whop gav dig den — en ws_-streng. Fjern ikke præfikset, og base64-kod den ikke. Hjælpefunktionen udleder nøglen.
2

Håndter hændelser på din server

Ét kald verificerer signaturen og returnerer den parsede hændelse. Hvis signaturen er forkert, kaster kaldet en fejl, og din handler ser aldrig payloaden.
Hjælpefunktionen returnerer den parsede body, ikke et typet hændelsesobjekt: et almindeligt objekt i TypeScript, en dict i Python og en Hash med symbolnøgler i Ruby. Forgren på type, og læs data som vist.
Udfør kun det nødvendige arbejde, før du svarer: verificer hændelsen, sæt arbejdet i en kø, og returner 200. TypeScript-eksemplet bruger waitUntil fra @vercel/functions. På andre runtimes skal du bruge dit frameworks funktion til baggrundsopgaver eller en jobkø.
Whop signerer strengen {webhook-id}.{webhook-timestamp}.{raw body} med HMAC-SHA256. Nøglen er din ws_...-hemmelighed. Headeren webhook-signature indeholder resultatet i base64: v1,<signature>.Sådan verificerer du en request: beregn HMAC’en over den rå request-body, kod resultatet i base64, og sammenlign det med headerværdien med en sammenligning i konstant tid. Afvis en request, hvis dens webhook-timestamp afviger mere end 5 minutter fra det aktuelle tidspunkt. Det forhindrer replay-angreb. SDK’ernes verifikatorer anvender automatisk denne grænse.

Test dit endpoint

  • Send en testhændelse. Åbn webhookens menu i dashboardet, og vælg en testhændelse. Eller kald POST /api/v1/webhooks/{id}/test. Whop sender en eksempel-payload til din URL og returnerer svarstatus og body fra din server.
  • Undersøg leveringer. Whop gemmer hver levering i 30 dage: requesten, svarkoden, svarets body og tidsforløbet. Se leveringerne i dashboardet eller med GET /api/v1/webhooks/{id}/deliveries.
En webhook-URL skal kunne nås fra det offentlige internet. Whop afviser localhost og adresser på private netværk. Til lokal udvikling kan du bruge ngrok eller Cloudflare Tunnel til at videresende en offentlig URL til din maskine. Registrer tunnel-URL’en.

Levering

Svar med en 2xx-status på mindre end 5 sekunder. Alle andre resultater er mislykkede forsøg: en timeout, en fejlstatus eller en omdirigering. Whop følger ikke omdirigeringer. Whop leverer hver hændelse mindst én gang. Den samme hændelse kan ankomme mere end én gang. Gør din handler idempotent. Hvert genforsøg på en levering har samme webhook-id. Gem webhook-id, og ignorer dubletter. Whop prøver mislykkede leveringer igen i cirka 3 dage. Efter det første forsøg prøver Whop igen 12 gange med stigende forsinkelser: 30 sekunder, 2 minutter, 8 minutter, 30 minutter, 1 time, 3 timer, 6 timer og derefter hver 12. time. Hele tidsplanen er cirka 71 timer. Rækkefølgen af leveringer er ikke garanteret. En nyere hændelse kan ankomme før en ældre hændelse. Behandl hver hændelse uafhængigt. Hvis rækkefølgen er vigtig, skal du læse den aktuelle tilstand fra API’et. Whop deaktiverer endpoints, der bliver ved med at fejle. Hvis alle leveringer til dit endpoint fejler i 24 timer, sender Whop en advarsels-e-mail til din konto. Hvis fejlene fortsætter i 72 timer, og 10 eller flere leveringer er mislykkedes, deaktiverer Whop webhooken og sender en ny e-mail. For at aktivere webhooken igen skal du bruge dashboardet eller sende PATCH /api/v1/webhooks/{id} med "enabled": true. Det nulstiller fejlhistorikken. Whop sender ikke de hændelser, der indtraf, mens webhooken var slået fra. Læs API’et for at finde de data, du gik glip af.

Fejlfind levering af webhooks

Løs signaturfejl, genforsøg, dublerede hændelser og problemer med lokale tunneler.

Hændelser og versioner

To versionsfelter styrer de data, dit endpoint modtager:
  • api_version — konvolutformatet. Brug v1. Denne side beskriver kun v1. De ældre formater v2 og v5 findes til gamle integrationer og bruger ikke Standard Webhooks-signaturer. Brug dem ikke til nye integrationer.
  • api_version_date — den daterede API-version, der bestemmer formen på data og på selve konvolutten (for eksempel har fastlåsninger fra 2026-08-14 account_id, hvor ældre fastlåsninger har company_id). Den fungerer på samme måde som headeren Api-Version-Date ved REST-læsninger. Angiv den, når du opretter en webhook med API’et. Så forbliver payloadens form stabil, når API’et ændres. Webhooks uden fastlåsning beholder deres oprindelige payload- og konvolutform. Undtagelse: ressourcer, der kun findes i det aktuelle API (kort, varianter, overførsler, swaps, indbetalinger, eksporter), modtager altid den nyeste data-form — konvolutten følger stadig fastlåsningen.
Hændelsesnavne har formatet resource.action. Hver hændelse i tabellen linker til en referenceside med payload-skemaet:

Næste trin

Modtag betalinger

Brug payment.succeeded-webhooks med checkout til at gennemføre ordrer.

Gem betalingsmetoder

Brug setup intents og webhooks til at opkræve kunder senere.

Quickstart

Se, hvordan webhooks fungerer med checkout, overførsler og KYC.

API-reference for webhooks

Alle endpoints og felter: oprettelse, opdatering, test, leveringer.