Skip to main content
Un webhook est une requête 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.
Les webhooks Whop utilisent la spécification Standard Webhooks. Les SDK Whop vérifient la signature et analysent l’événement en un seul appel. Pour Go, utilisez la section Vérifier sans SDK en bas de cette page.

À quoi ressemble un webhook

Chaque événement correspond à une requête POST :
L’enveloppe suit l’épinglage 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 .updated qui capturent les modifications (account.updated, product.updated, plan.updated et shipment.updated) : un objet contenant les anciennes valeurs des champs de data qui 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’épinglage api_version_date de votre webhook, de la même façon que data.

Récupérer un paiement d’abonnement

Lorsque la banque demande à l’acheteur de vérifier un débit hors session, Whop émet payment.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

La réponse contient 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é.
N’effectuez que le travail nécessaire avant de répondre : vérifiez l’événement, placez le travail dans une file d’attente et renvoyez 200. L’exemple TypeScript utilise waitUntil de @vercel/functions. Sur d’autres environnements d’exécution, utilisez la fonction de tâche en arrière-plan de votre framework ou une file de tâches.
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ême webhook-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. Utilisez v1. Cette page ne décrit que v1. Les anciens formats v2 et v5 existent 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 de data et de l’enveloppe elle-même (par exemple, les épinglages à partir de 2026-08-14 portent account_id là où les plus anciens portent company_id). Il fonctionne comme l’en-tête Api-Version-Date pour 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 de data — l’enveloppe suit toujours l’épinglage.
Les noms d’événements ont le format 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.