Tester les webhooks Polar en local avec la CLI Polar

Pour tester les webhooks Polar localement, exécutez votre gestionnaire de webhook, installez et authentifiez la CLI Polar, puis utilisez polar listen http://localhost:3000/api/webhooks/polar pour relayer les événements signés directement sur votre machine. Copiez le secret temporaire imprimé par l'auditeur dans POLAR_WEBHOOK_SECRET, vérifiez le corps brut avant de le traiter et déclenchez un événement de paiement, de commande, de remboursement ou d'abonnement sandbox.

Pourquoi Polar CLI est le flux de travail local le plus simple

Un point de terminaison de webhook de production normal doit être accessible publiquement via HTTPS. Polar propose un écouteur local spécialement conçu, vous n'avez donc pas besoin de créer un point de terminaison permanent ou de coller à plusieurs reprises des URL de rappel temporaires dans un tableau de bord. La CLI se connecte à votre organisation, affiche un secret de signature de session, reçoit des événements et les transmet à l'URL locale que vous fournissez.

Officiel de Polar documentation du webhook local utilise polar listen http://localhost:3000/. Pointez-le sur le chemin complet lorsque votre application gère les webhooks sous un itinéraire tel que /api/webhooks/polar. Cela détecte les erreurs de chemin avant la production et conserve le même gestionnaire d'application que vous avez l'intention de déployer.

Installez la CLI et commencez à écouter

1. Démarrez votre application et confirmez que sa route POST est disponible localement.
2. Installez Polar CLI à l'aide de la commande de la documentation officielle.
3. Courir polar login et autorisez le bon compte.
4. Commencer polar listen http://localhost:3000/api/webhooks/polar.
5. Sélectionnez l'organisation propriétaire de vos produits sandbox.
6. Copiez le secret de session affiché dans POLAR_WEBHOOK_SECRET et redémarrez votre application si son environnement est chargé uniquement au démarrage.
7. Déclenchez une action sandbox et comparez l’état de livraison CLI avec vos journaux locaux.

Le secret de l'auditeur fait partie de la session locale. Ne présumez pas qu’il s’agit d’un secret de point de terminaison de tableau de bord ou que vous réutilisez une valeur de production. Si vous vous reconnectez et recevez un secret différent, mettez à jour l'environnement local avant de tester à nouveau.

Créer un gestionnaire de routeur d'application Next.js

Polar suit la spécification Standard Webhooks. Une livraison comprend webhook-id, webhook-timestamp, et webhook-signature. La vérification doit utiliser le corps brut exact de la demande ; appeler request.json() d'abord et sérialiser à nouveau l'objet peut modifier les octets signés.

// app/api/webhooks/polar/route.ts
import { Webhook } from 'standardwebhooks';

export const runtime = 'nodejs';

export async function POST(request: Request) {
  const rawBody = await request.text();
  const secret = process.env.POLAR_WEBHOOK_SECRET;
  if (!secret) {
    return new Response('Webhook secret is not configured', { status: 500 });
  }

  const headers = {
    'webhook-id': request.headers.get('webhook-id') ?? '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') ?? '',
    'webhook-signature': request.headers.get('webhook-signature') ?? '',
  };

  try {
    const encodedSecret = Buffer.from(secret.trim(), 'utf8').toString('base64');
    const payload = new Webhook(encodedSecret).verify(rawBody, headers);
    await acceptPolarEvent(headers['webhook-id'], payload);
    return Response.json({ received: true });
  } catch {
    return new Response('Invalid signature', { status: 403 });
  }
}

Les polaires documents de livraison soulève un piège courant de vérification personnalisée : les bibliothèques Webhooks standard attendent un secret codé en Base64, tandis que Polar fournit une chaîne secrète normale. Les assistants du SDK Polar gèrent cette conversion automatiquement. Lors de l'utilisation standardwebhooks directement, encodez en Base64 le secret polaire complet comme indiqué ci-dessus.

Préférez un adaptateur de framework officiel lorsqu'il est disponible

Polar publie des adaptateurs qui combinent la vérification de signature avec des gestionnaires de charge utile typés. Le fonctionnaire Documentation de l'adaptateur express fournit des rappels granulaires pour les événements de paiement, de commande, de remboursement, d'avantages et d'abonnement. Un adaptateur réduit le risque d’implémentation incorrecte de l’analyse d’en-tête ou du codage secret.

import express from 'express';
import { Webhooks } from '@polar-sh/express';

const app = express();
app.use(express.json());
app.post('/webhooks/polar', Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET,
  onOrderPaid: async (event) => {
    await queueOrderPaid(event.data);
  },
  onSubscriptionActive: async (event) => {
    await queueSubscriptionActive(event.data);
  },
}));
app.listen(3000);

Suivez l’ordre documenté des middlewares de l’adaptateur pour la version que vous installez. Si vous utilisez plutôt un vérificateur générique, conservez explicitement le corps brut. Ne mélangez pas un adaptateur qui lit le flux avec un middleware qui le consomme en premier.

Quels événements polaires devriez-vous tester ?

Événements de paiement

Les événements de paiement permettent de suivre une session avant qu'elle ne devienne une commande payante. Testez la réussite et les états abandonnés ou mis à jour sans accorder l'accès simplement parce qu'une extraction a été créée. La commande payée ou l'abonnement actif doit rester le signal de droit faisant autorité.

Commande payée et remboursée

Pour un événement payé par commande, associez le client et le produit Polar à votre compte interne, puis accordez l'avantage acheté une seule fois. Les événements de remboursement doivent annuler uniquement le droit concerné conformément à votre politique de remboursement. Stockez les identifiants des fournisseurs afin que l'assistance puisse rapprocher l'événement avec Polar.

Événements du cycle de vie des abonnements

Création de tests, activation, mises à jour, annulation, révocation et tout comportement en retard pris en charge par votre produit. Une demande d'annulation ne peut pas signifier que l'accès prend fin immédiatement. Statut du magasin et dates d'effet au lieu de réduire le cycle de vie à un seul is_active drapeau.

Subventions de prestations

Si votre intégration utilise les avantages Polar, testez la création, la mise à jour et la révocation des subventions indépendamment des événements de facturation. Faites converger les gestionnaires vers l’état souhaité afin que recevoir deux fois la même subvention ne fournisse pas de ressources en double.

Rendre chaque événement idempotent

La livraison du réseau n’est pas une transaction unique. Un gestionnaire peut valider son travail de base de données et perdre la réponse, obligeant l'expéditeur à réessayer. Utiliser webhook-id en tant que clé de livraison unique et réclamez-la dans la même transaction qui met à jour l'état de votre application.

await db.transaction(async (tx) => {
  const firstDelivery = await tx.webhookReceipts.insertIfAbsent({
    provider: 'polar',
    deliveryId: webhookId,
  });
  if (!firstDelivery) return;

  await applyPolarEvent(tx, payload);
  await tx.outbox.enqueue('polar-event-accepted', { webhookId });
});

Renvoie une réponse 2xx pour un duplicata déjà terminé. Ne effectuez pas de déduplication uniquement par client ou ID d'abonnement, car de nombreux événements légitimes ciblent la même ressource. Le guide de nouvelle tentative de webhook et d'idempotence couvre les modèles de boîte de réception et de boîte d'envoi plus en détail.

Gardez le travail de reconnaissance court

Vérifiez la demande, conservez-la ou mettez en file d'attente une tâche durable et renvoyez le succès. La messagerie électronique, la génération de licences, l'accès au référentiel, les analyses et les appels d'API tiers doivent s'exécuter de manière asynchrone. Un accusé de réception rapide réduit les tentatives tandis qu'une écriture durable empêche les événements de disparaître si le processus se termine après son retour.

Les types d'événements inconnus doivent être enregistrés et reconnus après une vérification de signature valide. Polar peut ajouter des types d'événements au fil du temps ; l'ajout de chaque valeur inconnue convertit un ajout de schéma inoffensif en échecs de livraison répétés.

Résoudre les pannes de l'hôte local du webhook Polar

La CLI se connecte mais la route renvoie 404

Suivez l'itinéraire local complet jusqu'à polar listen, pas seulement le port. Dans Next.js App Router, assurez-vous que le fichier est nommé route.ts et exportations POST. Un navigateur GET renvoyant 404 ne prouve pas que la route POST est manquante, alors testez avec curl -X POST.

Chaque requête renvoie 403

Confirmez que l'application a chargé le secret imprimé par la session CLI en cours. Conservez le corps brut et les trois en-têtes Webhooks standard. Si vous utilisez la bibliothèque générique, encodez en Base64 le secret Polar exactement une fois ; si vous utilisez un assistant du SDK Polar, transmettez le secret d'origine et laissez le SDK gérer l'encodage.

Aucun événement n'apparaît après un paiement

Vérifiez que la CLI est connectée à la même organisation et au même environnement où l'action s'est produite. Gardez le terminal d'écoute ouvert, utilisez les ressources du bac à sable et confirmez que votre action atteint réellement l'état de l'événement auquel vous êtes abonné.

Les événements sont traités deux fois

Ajouter une contrainte unique pour webhook-id et renvoie le succès pour les doublons. Vérifiez si une exception se produit après la mise à jour de votre état mais avant la réponse. Déplacez les effets secondaires lents vers un travailleur sauvegardé dans la boîte d'envoi.

Une ancienne demande capturée échoue à la vérification

La vérification standard des Webhooks inclut un horodatage pour limiter les attaques par réexécution. Une ancienne capture devrait échouer dans la fenêtre de vérification normale. Pour les tests de logique métier, vérifiez une nouvelle livraison une fois et enregistrez un élément de charge utile nettoyé derrière la limite d'authentification.

Liste de contrôle de sécurité avant la production

• Utilisez des secrets de point de terminaison local, sandbox et de production distincts.
• Vérifiez le corps brut, l'horodatage, l'ID de livraison et la signature avant le traitement.
• Conservez les jetons d'API et les secrets des webhooks dans des variables d'environnement réservées au serveur.
• Dédupliquer par webhook-id et valider les identifiants des produits, de l'organisation et des clients.
• Rédigez les e-mails des clients, les données de facturation, les métadonnées et les charges utiles complètes à partir des journaux partagés.
• Appliquez des limites de taille de requête et surveillez les signatures invalides répétées.
• Remplacez l'écouteur local par un point de terminaison HTTPS stable et testez un nouveau flux sandbox avant d'activer les produits en direct.

La CLI Polar supprime la boucle de déploiement, mais elle ne doit pas supprimer les contrôles de production. Gardez la vérification de signature, l'idempotence, le filtrage des événements et le traitement durable activés localement afin que le code que vous testez soit celui que vous envoyez. Pour plus de détails sur la vérification indépendante du framework, lisez le guide de vérification de la signature du webhook et le général workflow de débogage local.