POST que Whop envoie à votre serveur lorsqu’un événement se produit. Exemples d’événements : un paiement réussit, une adhésion s’active, un litige s’ouvre. Vous enregistrez une URL publique. Whop envoie un événement JSON signé à cette URL chaque fois que l’un des événements auxquels vous êtes abonné se produit.
À quoi ressemble un webhook
Chaque événement correspond à une requêtePOST :
api_version_date de votre webhook, de la même façon que data. Les webhooks épinglés avant 2026-08-14 — ainsi que les webhooks sans épinglage — reçoivent le champ du compte sous le nom company_id au lieu de account_id.
Les en-têtes de la requête HTTP sont versionnés de la même manière : tout futur changement d’en-tête est livré sous la forme d’une version datée de l’API, et votre épinglage conserve les en-têtes avec lesquels vous avez intégré. Quatre en-têtes sont contractuellement figés et ne changent dans aucune version : webhook-id, webhook-signature, webhook-timestamp et content-type — la vérification de signature fonctionne de façon identique quel que soit l’épinglage.
Un champ facultatif de l’enveloppe décrit ce qui a changé :
previous_attributes— présent sur les événements.updatedqui capturent les modifications (account.updated,product.updated,plan.updatedetshipment.updated) : un objet contenant les anciennes valeurs des champs dedataqui ont changé, indexées par nom de champ. Renommer le compte en “Shine Time Auto Detailing” livre{"title": "Webb's Mobile Detailing"}— la valeur qu’avait chaque champ modifié avant l’écriture. Lorsque le champ est absent, aucune capture des modifications n’était disponible pour l’événement. Les valeurs suivent l’épinglageapi_version_datede votre webhook, de la même façon quedata.
Récupérer un paiement d’abonnement
Lorsque la banque demande à l’acheteur de vérifier un débit hors session, Whop émetpayment.requires_action. Envoyez son data.recovery_url à l’acheteur pour qu’il puisse se connecter à Whop et effectuer l’authentification 3D Secure pour ce paiement. Les checkouts en session ne l’émettent jamais, car l’acheteur est déjà en train de relever le défi. Un renouvellement d’abonnement échoué émet aussi payment.failed. Consultez data.decline_code et data.failure_message pour connaître la raison lorsqu’elle est disponible, et utilisez là aussi data.recovery_url lorsqu’il est présent.
Le même champ recovery_url est disponible lorsque vous récupérez la ressource Payment. Les listes de paiements n’incluent pas les liens de récupération. Il vaut null lorsque la récupération par authentification n’est pas disponible ou que vous ne disposez pas de member:basic:read. Ouvrir le lien ne déclenche aucun débit : l’acheteur doit confirmer, et Whop vérifie si le paiement peut encore être récupéré. Après la récupération, continuez à gérer payment.succeeded ou payment.failed pour connaître l’issue.
Créer un webhook
- API
- Tableau de bord
webhook_secret. L’API n’affiche cette valeur qu’une seule fois. Enregistrez-la immédiatement. Consultez la référence de l’API Webhooks pour tous les champs, y compris resource_id (le compte ou l’application propriétaire du webhook) et child_resource_events. Un webhook appartenant à une application reçoit aussi les événements d’installation et de désinstallation de cette application. Consultez Installations d’application.Vérifier et gérer les événements
Vérifiez toujours la signature avant d’utiliser une charge utile.1
Enregistrer votre secret de signature
La vérification nécessite le secret, pas un client SDK. Enregistrez la valeur renvoyée par l’API sous
WHOP_WEBHOOK_SECRET, et transmettez-la à la fonction utilitaire exactement telle que Whop vous l’a fournie — une chaîne ws_. Ne retirez pas le préfixe et ne l’encodez pas en base64. La fonction utilitaire dérive la clé.2
Gérer les événements sur votre serveur
Un seul appel vérifie la signature et renvoie l’événement analysé. Si la signature est incorrecte, l’appel lève une erreur et votre gestionnaire ne voit jamais la charge utile.La fonction utilitaire renvoie le corps analysé, et non un objet événement typé : un objet simple en TypeScript, un
dict en Python et un Hash à clés symboles en Ruby. Faites un branchement sur type et lisez data comme indiqué.Vérifier sans SDK
Vérifier sans SDK
Whop signe la chaîne
{webhook-id}.{webhook-timestamp}.{raw body} avec HMAC-SHA256. La clé est votre secret ws_.... L’en-tête webhook-signature contient le résultat en base64 : v1,<signature>.Pour vérifier une requête : calculez le HMAC sur le corps brut de la requête, encodez le résultat en base64 et comparez-le à la valeur de l’en-tête avec une comparaison à temps constant. Rejetez une requête si son webhook-timestamp s’écarte de plus de 5 minutes de l’heure actuelle. Cela empêche les attaques par rejeu. Les vérificateurs des SDK appliquent cette limite automatiquement.Tester votre endpoint
- Envoyez un événement de test. Dans le tableau de bord, ouvrez le menu du webhook et sélectionnez un événement de test. Ou appelez
POST /api/v1/webhooks/{id}/test. Whop envoie une charge utile d’exemple à votre URL et renvoie le statut et le corps de la réponse de votre serveur. - Examinez les livraisons. Whop conserve chaque livraison pendant 30 jours : la requête, le code de réponse, le corps de la réponse et la durée. Consultez les livraisons dans le tableau de bord ou avec
GET /api/v1/webhooks/{id}/deliveries.
L’URL d’un webhook doit être accessible depuis l’internet public. Whop rejette
localhost et les adresses de réseau privé. Pour le développement local, utilisez ngrok ou Cloudflare Tunnel pour rediriger une URL publique vers votre machine. Enregistrez l’URL du tunnel.Livraison
Répondez avec un statut 2xx en moins de 5 secondes. Tous les autres résultats sont des tentatives échouées : un délai dépassé, un statut d’erreur ou une redirection. Whop ne suit pas les redirections. Whop livre chaque événement au moins une fois. Le même événement peut arriver plusieurs fois. Rendez votre gestionnaire idempotent. Chaque nouvelle tentative d’une livraison porte le mêmewebhook-id. Enregistrez le webhook-id et ignorez les doublons.
Whop relance les livraisons échouées pendant environ 3 jours. Après la première tentative, Whop effectue 12 nouvelles tentatives avec des délais croissants : 30 secondes, 2 minutes, 8 minutes, 30 minutes, 1 heure, 3 heures, 6 heures, puis toutes les 12 heures. Le calendrier complet couvre environ 71 heures.
L’ordre des livraisons n’est pas garanti. Un événement plus récent peut arriver avant un événement plus ancien. Traitez chaque événement indépendamment. Si l’ordre est important, lisez l’état actuel depuis l’API.
Whop désactive les endpoints qui continuent d’échouer. Si toutes les livraisons vers votre endpoint échouent pendant 24 heures, Whop envoie un e-mail d’avertissement à votre compte. Si les échecs se poursuivent pendant 72 heures et que 10 livraisons ou plus ont échoué, Whop désactive le webhook et envoie un second e-mail. Pour réactiver le webhook, utilisez le tableau de bord ou envoyez PATCH /api/v1/webhooks/{id} avec "enabled": true. Cela réinitialise l’historique des échecs. Whop n’envoie pas les événements survenus pendant que le webhook était désactivé. Consultez l’API pour retrouver les données manquées.
Résoudre les problèmes de livraison des webhooks
Corrigez les échecs de signature, les nouvelles tentatives, les événements en double et les problèmes de tunnel local.
Événements et versions
Deux champs de version contrôlent les données que reçoit votre endpoint :api_version— le format de l’enveloppe. Utilisezv1. Cette page ne décrit quev1. Les anciens formatsv2etv5existent pour les anciennes intégrations et n’utilisent pas les signatures Standard Webhooks. Ne les utilisez pas pour de nouvelles intégrations.api_version_date— la version datée de l’API qui définit la forme dedataet de l’enveloppe elle-même (par exemple, les épinglages à partir de2026-08-14portentaccount_idlà où les plus anciens portentcompany_id). Il fonctionne comme l’en-têteApi-Version-Datepour les lectures REST. Définissez-le lorsque vous créez un webhook avec l’API. La forme de la charge utile reste alors stable lorsque l’API évolue. Les webhooks sans épinglage conservent leur forme initiale de charge utile et d’enveloppe. Exception : les ressources qui n’existent que dans l’API actuelle (cartes, variantes, transferts, swaps, dépôts, exports) reçoivent toujours la forme la plus récente dedata— l’enveloppe suit toujours l’épinglage.
resource.action. Chaque événement du tableau renvoie vers une page de référence contenant le schéma de la charge utile :
Étapes suivantes
Accepter des paiements
Utilisez les webhooks
payment.succeeded avec le checkout pour traiter les commandes.Enregistrer des moyens de paiement
Utilisez les setup intents et les webhooks pour débiter vos clients ultérieurement.
Démarrage rapide
Découvrez comment les webhooks fonctionnent avec le checkout, les transferts et le KYC.
Référence de l'API Webhooks
Tous les endpoints et champs : création, mise à jour, test, livraisons.

