Le simulateur de Webhooks PayPal peut-il envoyer des messages à localhost ?

Pas directement. Exposez votre route de webhook locale avec un tunnel HTTPS public, puis entrez cette URL HTTPS dans le simulateur. PayPal nécessite un auditeur qu'il peut atteindre via Internet.

Pourquoi la vérification de la signature PayPal échoue-t-elle pour un événement de simulation ?

Les événements du simulateur simulé ne peuvent pas être publiés sur le point de terminaison de vérification-webhook-signature de PayPal. PayPal documente WEBHOOK_ID pour les signatures du simulateur d'auto-vérification ; utilisez un véritable événement d'application sandbox pour tester la vérification de la publication.

Quelle est la différence entre le Sandbox PayPal et les webhooks du simulateur ?

Les webhooks du simulateur sont des charges utiles fictives et indépendantes des applications pour les tests d'écoute. Les webhooks de l'application Sandbox résultent de l'activité du Sandbox, utilisent le véritable ID de webhook de l'application, apparaissent dans ses outils d'événements et prennent en charge le flux de travail de vérification normal.

Quel statut HTTP un webhook PayPal doit-il renvoyer ?

Renvoyez une réponse 2xx une fois l’événement vérifié et durablement accepté. Rejetez les signatures non valides et déplacez les tâches d'exécution ou de notification lentes vers une file d'attente afin que la livraison n'expire pas.

Tester les webhooks PayPal Sandbox sur localhost

Pour tester les webhooks sandbox PayPal sur localhost, exécutez votre écouteur localement, exposez son itinéraire via un tunnel HTTPS public, enregistrez cette URL sur une application sandbox et déclenchez soit une véritable transaction sandbox, soit un événement simulé dans le simulateur de webhooks de PayPal. Gardez la vérification de signature activée : les événements du simulateur et les événements sandbox associés à l'application ont une différence de vérification importante expliquée ci-dessous.

Pourquoi PayPal ne peut pas envoyer directement à localhost

PayPal fournit des notifications de webhook à partir de ses propres serveurs. Une adresse telle que http://localhost:3000/api/paypal pointe vers la machine PayPal du point de vue de PayPal, pas du vôtre. Un localhost tunnel donne au processus local une adresse HTTPS publique tout en laissant l'application sur votre ordinateur.

La documentation officielle du PayPal Webhooks Simulator indique que son écouteur doit être accessible via HTTPS sur le port 443. Un tunnel gère ce point de terminaison TLS public et transmet la demande à n'importe quel port local, tel que 3000 ou 8080.

Choisissez le bon chemin de test PayPal

Événements de simulation simulés pour le développement des auditeurs

Le simulateur peut envoyer des événements représentatifs, notamment des captures de paiement, des remboursements et des événements de facturation, sans créer de transaction. Il s'agit du moyen le plus rapide de confirmer le routage, l'analyse JSON, les codes de réponse et la répartition des événements. Les événements simulés ne sont pas liés à une application REST, n'apparaissent pas dans l'observateur d'événements webhook de l'application, ne peuvent pas être renvoyés et ne représentent pas de transactions réelles.

Événements sandbox réels pour un comportement de bout en bout

Pour une intégration réaliste, créez une application REST dans le tableau de bord du développeur PayPal, ajoutez le point de terminaison du tunnel en tant que webhook, sélectionnez les types d'événements requis et effectuez une extraction sandbox ou une opération API. Ces événements appartiennent à l'application sandbox et utilisent les mêmes informations d'identification d'application, ID de webhook, observateur d'événements et workflow de renvoi que vous utiliserez avant la production.

Configurer un webhook PayPal sur localhost

Démarrez votre application et confirmez que l'itinéraire fonctionne localement : curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'.
Exécutez npx portpreview 3000 et copiez l'URL HTTPS générée.
Créez le rappel complet, par exemple https://your-subdomain.portpreview.dev/api/webhooks/paypal.
Pour des tests simulés, collez-le dans le simulateur Webhooks et sélectionnez un événement. Pour tester l'application, ajoutez-la dans les paramètres webhook de votre application sandbox REST.
Envoyez un événement et inspectez la méthode entrante, les en-têtes PayPal, le corps brut, les journaux du gestionnaire et la réponse HTTP.

Abonnez-vous uniquement aux événements gérés par votre application. Un abonnement étendu crée du bruit et facilite l'exécution accidentelle d'une logique métier pour un événement que vous n'avez jamais modélisé.

A practical Express listener

import express from 'express';

const app = express();
app.use(express.json({ verify: (req, _res, buf) => {
  req.rawBody = Buffer.from(buf);
}}));

app.post('/api/webhooks/paypal', async (req, res) => {
  const event = req.body;

  // Verify first; do not fulfill an order from untrusted JSON.
  const verified = await verifyPayPal(req.headers, event);
  if (!verified) return res.status(401).send('invalid signature');

  // Claim the event ID atomically so retries cannot duplicate work.
  const firstDelivery = await claimEvent(event.id);
  if (!firstDelivery) return res.sendStatus(200);

  if (event.event_type === 'PAYMENT.CAPTURE.COMPLETED') {
    await markOrderPaid(event.resource.id);
  }

  return res.sendStatus(200);
});

app.listen(3000);

Faites en sorte que le travail de reconnaissance soit court. Stockez l'événement, renvoyez une réponse 2xx et effectuez un travail lent de courrier électronique ou d'exécution dans une file d'attente. L'ID d'événement est la clé naturelle de l'idempotence ; appliquer une contrainte de base de données unique plutôt que de s'appuyer sur un ensemble en mémoire.

Vérifiez correctement les signatures PayPal

PayPal envoie des métadonnées de transmission dans des en-têtes comprenant PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG et PAYPAL-TRANSMISSION-TIME. Pour les événements associés à une application, vous pouvez soumettre ces valeurs, l'ID du webhook et l'événement à l'API sandbox /v1/notifications/verify-webhook-signature. Une réponse HTTP réussie ne suffit pas ; exiger que verification_status soit égal à SUCCESS. PayPal documente également la vérification cryptographique locale dans son guide d'intégration du webhook.

Avertissement concernant le simulateur : Le point de terminaison de vérification de publication de PayPal ne prend pas en charge les événements de simulation simulés. PayPal documente l'ID littéral du webhook WEBHOOK_ID pour l'auto-vérification d'une signature de simulateur. Ne confondez pas cette valeur spéciale avec le véritable identifiant de webhook attribué à une application sandbox. Si votre objectif immédiat est de tester l'API de publication elle-même, générez une véritable transaction sandbox au lieu d'un événement de simulation simulé.

Vérifiez que toute URL de certificat respecte les règles documentées de PayPal avant de le télécharger, conservez la représentation exacte de l'événement requise par la méthode de vérification et n'enregistrez jamais les jetons d'accès, les secrets client, les signatures ou les charges utiles de paiement complètes.

Testez les événements qui changent de l'argent ou des accès

PAYMENT.CAPTURE.COMPLETED : accordez l'exécution uniquement après avoir vérifié les identifiants de commande attendus, le montant, la devise et l'état de capture.
PAYMENT.CAPTURE.REFUNDED : annulez les droits en toute sécurité et prenez en charge les remboursements partiels.
Événements de commande de paiement : distinguer l'approbation d'une capture terminée ; l'approbation à elle seule ne constitue pas une preuve que les fonds ont été capturés.
Événements d'abonnement : test d'activation, suspension, annulation, échec de paiement et livraison hors commande par rapport à votre machine d'état de facturation.

Les événements du fournisseur sont des notifications et non des commandes de base de données incontestables. Pour les transitions sensibles, récupérez la ressource PayPal référencée avec les informations d'identification de l'API authentifiées et comparez-la avec votre propre enregistrement de commande.

Résoudre les problèmes de livraisons locales ayant échoué

Le simulateur ne peut pas se connecter

Confirmez que l'URL commence par https://, inclut le chemin exact du webhook et pointe toujours vers un tunnel en cours d'exécution. Testez vous-même l'URL publique avec curl. Un 404 signifie généralement que le chemin ou l'itinéraire cadre est erroné ; un 502 signifie généralement que le tunnel ne peut pas atteindre le processus local.

Le gestionnaire renvoie 401

Déterminez d'abord si l'événement provient du simulateur ou d'une application sandbox enregistrée. Vérifiez l’ID du webhook et la méthode de vérification en conséquence. Vérifiez ensuite que les proxys ont conservé tous les en-têtes PAYPAL-* et que vous ne mélangez pas les informations d'identification en direct avec api-m.sandbox.paypal.com.

PayPal tente ou marque l'échec de la livraison

Renvoyer un 2xx seulement après que l'événement ait été durablement accepté. Évitez les redirections, les pages d'erreur HTML, les middlewares d'authentification et les longues tâches synchrones sur l'itinéraire. Utilisez l'observateur d'événements pour les événements réels de l'application et le résultat du simulateur pour les diagnostics de livraison simulés. Consultez le guide de nouvelle tentative et d'idempotence pour connaître les modèles de traitement durables.

Liste de contrôle de sécurité avant la mise en ligne

Utilisez des informations d'identification de sandbox et de client actif, des ID de webhook et des secrets de point de terminaison distincts.
Vérifiez chaque signature avant d'analyser les champs commerciaux ou de changer d'état.
Dédupliquer via l'ID d'événement PayPal et rendre les transactions d'exécution atomiques.
Autoriser uniquement POST, limiter la taille de la demande, appliquer des limites de débit et garder l'URL du tunnel privée lorsque cela est possible.
Rédiger les données et informations d'identification des acheteurs à partir des journaux ; faites pivoter tout ce qui est exposé pendant le débogage.
Remplacez l'URL du tunnel temporaire par un point de terminaison de production stable et répétez les tests de signature et de nouvelle tentative.

Pour les schémas complets d'événement et de vérification, utilisez la référence principale de l'API Webhooks de PayPal. Pour plus de détails indépendants du framework sur les corps bruts et des comparaisons sûres, lisez le guide de vérification de signature webhook.