Paddle-Webhook-Simulator auf localhost verwenden

Um den Webhook-Simulator Paddle mit localhost zu verwenden, legen Sie Ihren lokalen Handler durch einen HTTPS-Tunnel frei, erstellen Sie ein Sandbox-Benachrichtigungsziel, das auf die öffentliche URL verweist, und führen Sie dann eine Einzelereignis- oder Lebenszyklussimulation mit diesem Ziel aus. Paddle sendet eine realistische Anfrage mit einem Paddle-Signature Header, so dass der gleiche Rohkörper-Verifikationspfad lokal und in der Produktion laufen kann.

Warum der Paddle-Simulator mehr ist als eine Nutzlast

Eine kopierte JSON-Hülle testet Ihre Switch-Anweisung. Der Paddle-Simulator testet das Netzwerkziel, die Provider-Header, das Signaturgeheimnis, den Antwortstatus und das Ereignisschema zusammen. Der Beamte Webhook-Simulatorübersicht unterstützt wiederverwendbare Einzelereignisse und Szenarien. Einzelne Ereignisse zielen auf einen Ereignistyp ab und können nach einem Lauf angepasst werden. Szenarien senden eine vordefinierte Sequenz für einen Lebenszyklus wie die Erstellung oder Erneuerung von Abonnements.

Die Szenariokonfiguration kann Nutzlasten mit bestehenden Paddle-Entitäten füllen und den Fluss variieren. Jeder Durchlauf erzeugt simulationsgeführte Ereignisdatensätze, in denen Sie die Nutzlast, die ausgehende Anforderung und die Endpunktantwort überprüfen können. Das macht den Simulator nützlich, um Zustandsübergänge zu debuggen und nicht nur zu beweisen, dass eine Route online ist.

Verbinden Sie einen lokalen Endpunkt mit der Paddle Sandbox

1. Starten Sie Ihre Bewerbung, zum Beispiel auf http://localhost:3000.
2. Hinzufügen einer POST-Route wie /api/webhooks/paddle.
3. Lauf npx portpreview 3000 und kopieren Sie die HTTPS-Adresse.
4. Erstellen Sie in der Sandbox Paddle ein Benachrichtigungsziel mit https://your-subdomain.portpreview.dev/api/webhooks/paddle.
5. Enthüllen und kopieren Sie das Endpunktgeheimnis dieses Ziels in PADDLE_WEBHOOK_SECRETEs ist nicht Ihr API Schlüssel.
6. Öffnen Sie Entwicklertools → Simulationen, wählen Sie ein einzelnes Ereignis oder Szenario aus, wählen Sie das Ziel aus, konfigurieren Sie es und führen Sie es aus.
7. Vergleichen Sie die Simulationsreaktion von Paddle mit Ihren lokalen Protokollen und dem anhaltenden Webhook-Beleg.

Verwenden Sie überall Sandbox-Ressourcen und Anmeldeinformationen. Das Mischen eines Live-Zielgeheimnisses mit einer Sandbox-Simulatoranforderung garantiert einen Signaturfehler, obwohl beide Zeichenfolgen plausibel aussehen.

Überprüfen Sie die Paddle-Signature Kopf

Paddle signiert jeden Webhook mit dem Geheimnis, das zum Benachrichtigungsziel gehört. Der Header enthält Komponenten, einschließlich eines Unix-Zeitstempels, der von ts und eine oder mehrere Signaturen, die durch h1Paddle kann Signaturversionen hinzufügen, also den Header analysieren, anstatt anzunehmen, dass er einen bloßen Hash enthält.

Die signierte Nutzlast ist der Zeitstempel, ein Doppelpunkt und der unberührte Anfragekörper. Paddle wendet HMAC-SHA256 mit dem Endpunktgeheimnis an. Seine Signaturprüfunterlagen empfiehlt ein offizielles SDK wo verfügbar und dokumentiert den manuellen Algorithmus. Erzwingen Sie immer die Zeitstempeltoleranz des SDK oder eine explizite Toleranz in Ihrem Verifier, um Wiederholungsangriffe zu begrenzen.

Bevorzugen Sie das offizielle SDK in Node

import express from 'express';
import { Environment, Paddle } from '@paddle/paddle-node-sdk';

const app = express();
const paddle = new Paddle(process.env.PADDLE_API_KEY, {
  environment: Environment.sandbox,
});

app.post(
  '/api/webhooks/paddle',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.header('paddle-signature') ?? '';
    const rawBody = req.body.toString('utf8');

    try {
      const event = await paddle.webhooks.unmarshal(
        rawBody,
        process.env.PADDLE_WEBHOOK_SECRET,
        signature,
      );

      await acceptOnce(event.eventId, event);
      return res.status(200).send('accepted');
    } catch (error) {
      return res.status(400).send('invalid webhook');
    }
  },
);

app.listen(3000);

Halterung express.raw() Vor jedem globalen express.json() Middleware für diese Route. In einem Fetch-Framework wie Next.js App Router verwenden await request.text() einmal und geben Sie genau diese Zeichenfolge an das SDK weiter. Der Beamte Webhook Quickstart zeigt diese rohe Körperanforderung.

Was die manuelle Überprüfung tun muss

1. Lesen Sie den Rohkörper ohne JSON-Normalisierung.
2. Analysieren Sie jede Semikolon-getrennte Header-Komponente und sammeln Sie unterstützt h1 Werte.
3. Ablehnen eines fehlenden, fehlgeformten oder unangemessen alten ts.
4. Berechnung HMAC_SHA256(secret, ts + ':' + rawBody).
5. Vergleichen Sie den erwarteten Digest mit Kandidatensignaturen mit einem Timing-sicheren Vergleich.
6. Erst nach einem Match analysieren Sie JSON und versenden Sie auf event_type.

Das Akzeptieren einer gültigen unterstützten Signatur ist während der geheimen Rotation wichtig, wenn mehr als eine Signatur vorhanden sein kann. Teilen Sie den Header nicht und nehmen Sie blind den zweiten Gegenstand. Protokollieren Sie nicht das Endpunktgeheimnis oder die vollständige Kundennutzlast, während Sie eine Fehlanpassung diagnostizieren.

Design-Simulationen rund um Billing-Invarianten

Zeichnungserstellung

Führen Sie ein Abonnementerstellungsszenario aus und vergewissern Sie sich, dass Ihre Datenbank zugehörige Transaktions- und Abonnementereignisse empfangen kann, ohne eine Netzwerkankunftsorder anzunehmen. Speichern Sie Paddle Entity IDs und aktualisieren Sie Datensätze idempotent. Der Antrag sollte genau einen Anspruch gewähren, auch wenn ein Antrag erneut gesendet wird.

Verlängerung und Zahlungsausfall

Führen Sie erfolgreiche Erneuerungs-, Vergangenheits- und Wiederherstellungspfade aus, die in Ihrer Szenariokonfiguration verfügbar sind. Separater Abrechnungsstatus von der Produktzugriffsrichtlinie: Ihre Nachfrist kann den Zugriff absichtlich aktiv halten, während Paddle ein Sammelproblem meldet.

Annullierung und geplante Änderungen

Unterscheiden Sie ein geplantes Abonnement von einem, das seine effektive Kündigung erreicht hat. Konserve next_billed_at, geplante Änderungsdaten und Anbieterstatus, anstatt den Lebenszyklus in is_active.

Aktualisierung der Stelle

Simulieren Sie Produkt-, Preis-, Kunden- und Abonnement-Updates, die Ihr Cache verbraucht. Ein Handler sollte unbekannte Ereignistypen sicher ignorieren und sie bestätigen, wenn die Signatur gültig ist; zukünftige Paddle-Zusätze sollten nicht zu einer endlosen Fehlerschleife werden.

Idempotenz und Ordnung bei jedem Lauf

Verwenden Sie die stabile ID des Webhook-Events als eindeutigen Schlüssel in einer Quittungstabelle. In einer Transaktion fügen Sie die Quittung ein, wenden Sie die Zustandsänderung an und enqueue Nebenwirkungen. Wenn Einfügen Konflikte, Rückkehr Erfolg ohne Wiederholung der Arbeit. Deduplizieren Sie nicht nur nach Entity ID, da viele legitime Updates auf ein Abonnement abzielen können.

Ereignisse können aus der Ordnung kommen. Vergleichen Sie die Ereigniszeit des Ereignisses oder rufen Sie die neueste Paddle-Entität ab, bevor Sie einen destruktiven Übergang anwenden. Speichern Sie den Status und den Zeitstempel des Anbieters und lehnen Sie ein älteres Update ab, das ein neueres überschreiben würde. Simulationsszenarien sind ideal, um diese Annahmen zu testen, da sie verbundene Sequenzen anstelle von isolierten Vorrichtungen erzeugen.

Fehlerbehebung Simulator-Localhost-Ausfälle

Destination Returns 404 oder 405

Überprüfen Sie, ob die öffentliche URL die vollständige Route enthält und dass die Route POST exportiert. Ein Browser GET ist kein gültiger Test eines reinen POST-Webhooks. Verwendung curl -X POST gegen die öffentliche URL, um das Tunnel-Routing von der Paddle-Konfiguration zu unterscheiden.

Destination gibt 400 zurück

prüfen, ob Paddle-Signature angekommen und bestätigt, dass das Endpunktgeheimnis zum ausgewählten Benachrichtigungsziel gehört. Stellen Sie sicher, dass kein Body Parser, Request Logger oder Middleware den Körper verbraucht oder neu formatiert hat. Der Simulator sendet überprüfbare Signaturen, wie in Paddle’s simulation run guide.

Destination gibt 500 oder mal aus

Beharren Sie schnell und verschieben Sie E-Mails, Provisionierung und ausgehende API-Anrufe in eine Warteschlange. 2xx nach dauerhafter Annahme zurückgeben. Das Werfen auf einen unbekannten Ereignistyp ist eine häufige Ursache für unnötige Fehler; Verwenden Sie einen Standardzweig, der ihn aufzeichnet und bestätigt.

Das Szenario verwendet unerwartete Daten

Überprüfen Sie, ob die Simulation automatisch generierte Werte verwendet oder mit echten Sandbox-Entitäten gefüllt ist. Überprüfen Sie die konfigurierten Szenariooptionen und die Laufereignisnutzlast, anstatt davon auszugehen, dass sie einen vorherigen Lauf widerspiegelt.

Sicherheits-Checkliste vor der Produktion

• Halten Sie API-Schlüssel und Benachrichtigungszielgeheimnisse getrennt und nur für Server bereit.
• Überprüfen Sie den Rohkörper, die Header-Signatur und den Zeitstempel vor der Verarbeitung.
• Verwenden Sie einen Timing-sicheren Vergleich oder einen offiziellen SDK-Verifier.
• Deduplizieren Sie Ereignis-IDs und behandeln Sie Out-of-Order-Updates.
• Tragen Sie Body Limits, POST-only Routing, redacted Logging und Rate Controls an.
• Verwenden Sie verschiedene Sandbox- und Live-Ziele, wiederholen Sie dann Simulationen und echte Sandbox-Flows, bevor Sie die Produktions-URL wechseln.

Der Simulator beweist Ihre Integration unter kontrollierten Lifecycle-Sequenzen; eine echte Sandbox-Checkout beweist zusätzlich Checkout-to-Entity-Beziehungen. Verwenden Sie beide, dann überprüfen Sie die allgemeine Webhook Signatur Guide und Idempotenzleitfaden vor dem Start.