PayPal-Sandbox-Webhooks auf localhost testen

Um PayPal-Sandbox-Webhooks auf localhost zu testen, führen Sie Ihren Listener lokal aus, legen Sie seine Route durch einen öffentlichen HTTPS-Tunnel offen, registrieren Sie diese URL in einer Sandbox-App und lösen Sie entweder eine echte Sandbox-Transaktion oder ein Scheinereignis im Webhooks-Simulator von PayPal aus. Lassen Sie die Signaturüberprüfung aktiviert: Bei Simulatorereignissen und App-assoziierten Sandbox-Ereignissen wird ein wichtiger Überprüfungsunterschied erklärt unten.

Warum PayPal nicht direkt an localhost senden kann

PayPal liefert Webhook-Benachrichtigungen von seinen eigenen Servern. Eine Adresse wie http://localhost:3000/api/paypal verweist aus PayPals Sicht auf den PayPal-Computer, nicht auf Ihren. Ein localhost-Tunnel gibt dem lokalen Prozess eine öffentliche HTTPS-Adresse, während die Anwendung auf Ihrem Computer verbleibt.

Die offizielle PayPal Webhooks Simulator-Dokumentation besagt, dass sein Listener über HTTPS auf Port 443 erreichbar sein muss. Ein Tunnel verarbeitet diesen öffentlichen TLS-Endpunkt und leitet die Anfrage an einen beliebigen lokalen Port wie 3000 oder 8080 weiter.

Wählen Sie den richtigen PayPal-Testpfad

Mock-Simulator-Ereignisse für die Listener-Entwicklung

Der Simulator kann repräsentative Ereignisse senden, einschließlich Zahlungserfassungen, Rückerstattungen und Abrechnungsereignisse, ohne eine Transaktion zu erstellen. Dies ist der schnellste Weg, um Routing, JSON-Parsing, Antwortcodes und den Ereignisversand zu bestätigen. Scheinereignisse sind nicht an eine REST-App gebunden, erscheinen nicht in der Webhook-Ereignisanzeige der App, können nicht erneut gesendet werden und stellen keine echten Transaktionen dar.

Echte Sandbox-Ereignisse für End-to-End-Verhalten

Für eine realistische Integration erstellen Sie eine REST-App im PayPal Developer Dashboard, fügen den Tunnelendpunkt als Webhook hinzu, wählen die erforderlichen Ereignistypen aus und führen einen Sandbox-Checkout oder einen API-Vorgang durch. Diese Ereignisse gehören zur Sandbox-App und verwenden dieselben App-Anmeldeinformationen, Webhook-ID, Ereignisanzeige und denselben Workflow zum erneuten Senden, die Sie vor der Produktion verwenden.

Einrichten eines PayPal-Webhooks auf localhost

1. Starten Sie Ihre Anwendung und bestätigen Sie, dass die Route lokal funktioniert: curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'.
2. Führen Sie npx portpreview 3000 aus und kopieren Sie die generierte HTTPS-URL.
3. Erstellen Sie den vollständigen Rückruf, zum Beispiel https://your-subdomain.portpreview.dev/api/webhooks/paypal.
4. Für Probetests fügen Sie es in den Webhooks-Simulator ein und wählen Sie ein Ereignis aus. Für App-Tests fügen Sie es unter den Webhook-Einstellungen Ihrer Sandbox-REST-App hinzu.
5. Senden Sie ein Ereignis und überprüfen Sie die eingehende Methode, PayPal-Header, Rohtext, Handler-Protokolle und HTTP-Antwort.

Abonnieren Sie nur Ereignisse, die Ihre Anwendung verarbeitet. Ein umfassendes Abonnement verursacht Lärm und erleichtert die versehentliche Ausführung von Geschäftslogik für ein Ereignis, das Sie nie modelliert haben.

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);

Bestätigungsarbeit kurz halten. Speichern Sie das Ereignis, geben Sie eine 2xx-Antwort zurück und führen Sie langsame E-Mail- oder Erfüllungsarbeiten in einer Warteschlange aus. Die Ereignis-ID ist der natürliche Idempotenzschlüssel; Erzwingen Sie eine eindeutige Datenbankbeschränkung, anstatt sich auf einen In-Memory-Satz zu verlassen.

PayPal-Signaturen korrekt überprüfen

PayPal sendet Übertragungsmetadaten in Headern, einschließlich PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG und PAYPAL-TRANSMISSION-TIME. Für App-assoziierte Ereignisse können Sie diese Werte, die Webhook-ID und das Ereignis an die Sandbox-API /v1/notifications/verify-webhook-signature senden. Eine erfolgreiche HTTP-Antwort reicht nicht aus; erfordern, dass verification_status gleich SUCCESS ist. PayPal dokumentiert auch die lokale kryptografische Überprüfung in seinem webhook-Integrationsleitfaden.

Simulator-Vorbehalt: Der Postback-Verifizierungsendpunkt von PayPal unterstützt keine Scheinsimulatorereignisse. PayPal dokumentiert die wörtliche Webhook-ID WEBHOOK_ID zur Selbstverifizierung einer Simulatorsignatur. Verwechseln Sie diesen Sonderwert nicht mit der echten Webhook-ID, die einer Sandbox-App zugewiesen ist. Wenn Ihr unmittelbares Ziel darin besteht, die Postback-API selbst zu testen, generieren Sie eine tatsächliche Sandbox-Transaktion anstelle eines Scheinsimulatorereignisses.

Bestätigen Sie, dass jede Zertifikat-URL den dokumentierten Regeln von PayPal entspricht, bevor Sie sie herunterladen, behalten Sie die genaue Ereignisdarstellung bei, die für die Verifizierungsmethode erforderlich ist, und protokollieren Sie niemals Zugriffstoken, Kundengeheimnisse, Signaturen oder vollständige Zahlungsnutzdaten.

Testen Sie die Ereignisse, die Geld wechseln oder darauf zugreifen

• PAYMENT.CAPTURE.COMPLETED: Erfüllung erst nach Überprüfung der erwarteten Bestellkennungen, des Betrags, der Währung und des Erfassungsstatus gewähren.
• PAYMENT.CAPTURE.REFUNDED: Ansprüche sicher umkehren und teilweise Rückerstattungen unterstützen.
• Checkout-Bestellereignisse: Unterscheidung zwischen Genehmigung und abgeschlossener Erfassung; Die Genehmigung allein ist kein Beweis dafür, dass Gelder eingezogen wurden.
• Abonnementereignisse: Testaktivierung, Aussetzung, Stornierung, fehlgeschlagene Zahlung und Lieferung außerhalb der Reihenfolge für Ihren Abrechnungsstatusautomaten.

Provider-Ereignisse sind Benachrichtigungen, keine unbestreitbaren Datenbankbefehle. Rufen Sie bei sensiblen Übergängen die referenzierte PayPal-Ressource mit authentifizierten API-Anmeldeinformationen ab und vergleichen Sie sie mit Ihrem eigenen Bestelldatensatz.

Fehlerbehebung bei fehlgeschlagenen lokalen Zustellungen

Der Simulator kann keine Verbindung herstellen

Bestätigen Sie, dass die URL mit https:// beginnt, den genauen Webhook-Pfad enthält und immer noch auf einen laufenden Tunnel verweist. Testen Sie die öffentliche URL selbst mit curl. Ein 404 bedeutet normalerweise, dass der Pfad oder die Rahmenroute falsch ist; Ein 502 bedeutet im Allgemeinen, dass der Tunnel den lokalen Prozess nicht erreichen kann.

Der Handler gibt 401

zurück.

Bestimmen Sie zunächst, ob das Ereignis vom Simulator oder einer registrierten Sandbox-App stammt. Überprüfen Sie die Webhook-ID und die Überprüfungsmethode entsprechend. Stellen Sie dann sicher, dass die Proxys alle PAYPAL-*-Header beibehalten und dass Sie keine Live-Anmeldeinformationen mit api-m.sandbox.paypal.com.

vermischen.

PayPal versucht es erneut oder markiert die Zustellung als fehlgeschlagen

Ein 2xx erst zurückgeben, nachdem das Ereignis dauerhaft akzeptiert wurde. Vermeiden Sie Weiterleitungen, HTML-Fehlerseiten, Authentifizierungs-Middleware und lange synchrone Jobs auf der Route. Verwenden Sie die Ereignisanzeige für echte App-Ereignisse und das Simulatorergebnis für die Diagnose einer Scheinzustellung. Dauerhafte Verarbeitungsmuster finden Sie im Retry and Idempotency Guide für dauerhafte Verarbeitungsmuster.

Sicherheitscheckliste vor dem Go-Live

• Verwenden Sie separate Sandbox- und Live-Client-Anmeldeinformationen, Webhook-IDs und Endpunktgeheimnisse.
• Überprüfen Sie jede Signatur, bevor Sie Geschäftsfelder analysieren oder den Status ändern.
• Deduplizieren Sie anhand der PayPal-Ereignis-ID und machen Sie Erfüllungstransaktionen atomar.
• Nur POST zulassen, Anforderungsgröße begrenzen, Ratenbeschränkungen anwenden und die Tunnel-URL nach Möglichkeit privat halten.
• Käuferdaten und Anmeldeinformationen aus Protokollen schwärzen; Drehen Sie alles, was während des Debuggens offengelegt wird.
• Ersetzen Sie die temporäre Tunnel-URL durch einen stabilen Produktionsendpunkt und wiederholen Sie die Signatur- und Wiederholungstests.

Für die vollständigen Ereignis- und Verifizierungsschemata verwenden Sie PayPals primäre Webhooks-API-Referenz. Für Framework-unabhängige Details zu Rohkörpern und sicheren Vergleichen lesen Sie den webhook-Signaturverifizierungsleitfaden.