POST-verzoek dat Whop naar je server stuurt wanneer er een event plaatsvindt. Voorbeelden van events: een betaling slaagt, een lidmaatschap wordt geactiveerd, een geschil wordt geopend. Je registreert een openbare URL. Whop stuurt telkens wanneer een van de events waarop je bent geabonneerd plaatsvindt een ondertekend JSON-event naar deze URL.
Hoe een webhook eruitziet
Elk event is éénPOST-verzoek:
api_version_date-pin van je webhook, op dezelfde manier als data. Webhooks die zijn vastgezet op een versie vóór 2026-08-14 — en webhooks zonder pin — ontvangen het accountveld als company_id in plaats van account_id.
De HTTP-requestheaders worden op dezelfde manier geversioneerd: elke toekomstige wijziging in headers wordt uitgebracht als een gedateerde API-versie, en je pin behoudt de headers waarmee je hebt geïntegreerd. Vier headers liggen contractueel vast en veranderen in geen enkele versie: webhook-id, webhook-signature, webhook-timestamp en content-type — handtekeningverificatie werkt op elke pin identiek.
Eén optioneel envelopeveld beschrijft wat er is gewijzigd:
previous_attributes— aanwezig bij.updated-events die wijzigingen vastleggen (account.updated,product.updated,plan.updatedenshipment.updated): een object met de oude waarden van de gewijzigdedata-velden, met de veldnaam als key. Als je het account hernoemt naar “Shine Time Auto Detailing”, levert dat{"title": "Webb's Mobile Detailing"}op — de waarde die elk gewijzigd veld vóór de schrijfactie had. Als het veld ontbreekt, was er voor het event geen vastlegging van wijzigingen beschikbaar. Waarden volgen deapi_version_date-pin van je webhook, op dezelfde manier alsdata.
Een abonnementsbetaling herstellen
Wanneer de bank de koper vraagt een off-session afschrijving te verifiëren, verstuurt Whoppayment.requires_action. Stuur de bijbehorende data.recovery_url naar de koper, zodat die kan inloggen bij Whop en 3D Secure voor die betaling kan voltooien. On-session checkouts versturen dit event nooit, omdat de koper de verificatie dan al voltooit. Een mislukte verlenging van een abonnement verstuurt ook payment.failed. Bekijk data.decline_code en data.failure_message voor de reden wanneer die beschikbaar is, en gebruik ook daar data.recovery_url wanneer die aanwezig is.
Hetzelfde veld recovery_url is beschikbaar wanneer je de Payment-resource ophaalt. Lijsten van betalingen bevatten geen herstellinks. Het is null wanneer herstel via authenticatie niet beschikbaar is of wanneer je member:basic:read niet hebt. Het openen van de link start geen afschrijving: de koper moet bevestigen, en Whop controleert of de betaling nog kan worden hersteld. Blijf na het herstel payment.succeeded of payment.failed afhandelen voor de uitkomst.
Een webhook aanmaken
- API
- Dashboard
webhook_secret. De API toont deze waarde maar één keer. Sla deze direct op. Zie de Webhooks API-referentie voor alle velden, waaronder resource_id (het account of de app die eigenaar is van de webhook) en child_resource_events. Een webhook die bij een app hoort, ontvangt ook de installatie- en de-installatie-events van die app. Zie App-installaties.Events verifiëren en afhandelen
Verifieer altijd de handtekening voordat je een payload gebruikt.1
Je ondertekeningsgeheim opslaan
Voor verificatie heb je het geheim nodig, geen SDK-client. Sla de waarde die de API teruggaf op als
WHOP_WEBHOOK_SECRET en geef deze precies zo door aan de helper als Whop hem aan je gaf — een ws_-string. Verwijder het prefix niet en codeer het niet in base64. De helper leidt de sleutel af.2
Events afhandelen op je server
Eén aanroep verifieert de handtekening en geeft het geparste event terug. Als de handtekening onjuist is, gooit de aanroep een fout en krijgt je handler de payload nooit te zien.De helper geeft de geparste body terug, geen getypeerd event-object: een gewoon object in TypeScript, een
dict in Python en een Hash met symbol-keys in Ruby. Vertak op type en lees data zoals getoond.Verifiëren zonder SDK
Verifiëren zonder SDK
Whop ondertekent de string
{webhook-id}.{webhook-timestamp}.{raw body} met HMAC-SHA256. De sleutel is je ws_...-geheim. De header webhook-signature bevat het resultaat in base64: v1,<signature>.Een verzoek verifiëren: bereken de HMAC over de onbewerkte request-body, codeer het resultaat in base64 en vergelijk het met de headerwaarde via een constant-time vergelijking. Weiger een verzoek als de webhook-timestamp meer dan 5 minuten van de huidige tijd afwijkt. Dit voorkomt replay-aanvallen. De verifiers van de SDK passen deze limiet automatisch toe.Je endpoint testen
- Verstuur een testevent. Open in het dashboard het menu van de webhook en selecteer een testevent. Of roep
POST /api/v1/webhooks/{id}/testaan. Whop stuurt een voorbeeldpayload naar je URL en geeft de antwoordstatus en body van je server terug. - Bekijk afleveringen. Whop bewaart elke aflevering 30 dagen: het verzoek, de antwoordcode, de antwoordbody en de timing. Bekijk de afleveringen in het dashboard of met
GET /api/v1/webhooks/{id}/deliveries.
Een webhook-URL moet bereikbaar zijn vanaf het openbare internet. Whop weigert
localhost en adressen in privénetwerken. Gebruik voor lokale ontwikkeling ngrok of Cloudflare Tunnel om een openbare URL naar je machine door te sturen. Registreer de tunnel-URL.Aflevering
Antwoord binnen 5 seconden met een 2xx-status. Alle andere resultaten zijn mislukte pogingen: een time-out, een foutstatus of een redirect. Whop volgt geen redirects. Whop levert elk event minstens één keer af. Hetzelfde event kan meer dan één keer aankomen. Maak je handler idempotent. Elke herhaalpoging van een aflevering heeft dezelfdewebhook-id. Sla de webhook-id op en negeer duplicaten.
Whop probeert mislukte afleveringen ongeveer 3 dagen opnieuw. Na de eerste poging probeert Whop het 12 keer opnieuw met oplopende vertragingen: 30 seconden, 2 minuten, 8 minuten, 30 minuten, 1 uur, 3 uur, 6 uur en daarna elke 12 uur. Het volledige schema beslaat ongeveer 71 uur.
De volgorde van afleveringen is niet gegarandeerd. Een nieuwer event kan vóór een ouder event aankomen. Verwerk elk event onafhankelijk. Als de volgorde belangrijk is, lees dan de huidige status uit via de API.
Whop schakelt endpoints uit die blijven falen. Als alle afleveringen naar je endpoint 24 uur lang mislukken, stuurt Whop een waarschuwingsmail naar je account. Als de mislukkingen 72 uur aanhouden en 10 of meer afleveringen zijn mislukt, schakelt Whop de webhook uit en stuurt een tweede e-mail. Gebruik het dashboard of stuur PATCH /api/v1/webhooks/{id} met "enabled": true om de webhook weer in te schakelen. Dit reset de geschiedenis van mislukkingen. Whop verstuurt de events die plaatsvonden terwijl de webhook was uitgeschakeld niet. Lees de API uit om de gemiste gegevens te vinden.
Problemen met webhookaflevering oplossen
Los handtekeningfouten, herhaalpogingen, dubbele events en problemen met lokale tunnels op.
Events en versies
Twee versievelden bepalen welke gegevens je endpoint ontvangt:api_version— het formaat van de envelope. Gebruikv1. Deze pagina beschrijft alleenv1. De verouderde formatenv2env5bestaan voor oude integraties en gebruiken geen Standard Webhooks-handtekeningen. Gebruik ze niet voor nieuwe integraties.api_version_date— de gedateerde API-versie die de vorm vandataen van de envelope zelf bepaalt (pins vanaf2026-08-14bevatten bijvoorbeeldaccount_idwaar oudere pinscompany_idbevatten). Het werkt hetzelfde als de headerApi-Version-Datebij REST-leesacties. Stel het in wanneer je een webhook aanmaakt met de API. Dan blijft de vorm van de payload stabiel wanneer de API verandert. Webhooks zonder pin behouden hun oorspronkelijke vorm van payload en envelope. Uitzondering: resources die alleen in de huidige API bestaan (kaarten, varianten, overboekingen, swaps, stortingen, exports) krijgen altijd de nieuwste vorm vandata— de envelope volgt nog steeds de pin.
resource.action. Elk event in de tabel linkt naar een referentiepagina met het payloadschema:
Volgende stappen
Betalingen accepteren
Gebruik
payment.succeeded-webhooks met checkout om orders af te handelen.Betaalmethoden opslaan
Gebruik setup intents en webhooks om klanten later te belasten.
Quickstart
Bekijk hoe webhooks samenwerken met checkout, overboekingen en KYC.
Webhooks API-referentie
Alle endpoints en velden: aanmaken, bijwerken, testen, afleveringen.

