Użyj symulatora webhooka Paddle na Localhost

Aby używać symulatora webhooka Paddle z hostem lokalnym, udostępnij lokalny moduł obsługi przez tunel HTTPS, utwórz miejsce docelowe powiadomień w piaskownicy, które wskazuje publiczny adres URL, a następnie uruchom symulację pojedynczego zdarzenia lub cyklu życia dla tego miejsca docelowego. Paddle wysyła realistyczne żądanie za pomocą pliku Paddle-Signature nagłówek, więc ta sama ścieżka weryfikacji surowej treści może działać lokalnie i w środowisku produkcyjnym.

Dlaczego symulator Paddle to coś więcej niż przykładowy ładunek

Skopiowane urządzenie JSON testuje instrukcję switch. Symulator Paddle testuje łącznie miejsce docelowe sieci, nagłówki dostawców, klucz podpisu, status odpowiedzi i schemat zdarzeń. Urzędnik przegląd symulatora webhooka obsługuje pojedyncze zdarzenia i scenariusze wielokrotnego użytku. Pojedyncze zdarzenia są przeznaczone dla jednego typu zdarzenia i można je dostosować po uruchomieniu. Scenariusze wysyłają predefiniowaną sekwencję cyklu życia, taką jak utworzenie lub odnowienie subskrypcji.

Konfiguracja scenariusza może zapełnić ładunki istniejącymi jednostkami Paddle i różnicować przepływ. Każde uruchomienie generuje rekordy zdarzeń symulacyjnych, w których można sprawdzić ładunek, żądanie wychodzące i odpowiedź punktu końcowego. Dzięki temu symulator jest przydatny do debugowania zmian stanów, a nie tylko do sprawdzania, czy trasa jest w trybie online.

Połącz lokalny punkt końcowy z piaskownicą Paddle

1. Uruchom aplikację np http://localhost:3000.
2. Dodaj trasę POST, taką jak /api/webhooks/paddle.
3. Uruchomić npx portpreview 3000 i skopiuj adres HTTPS.
4. W piaskownicy Paddle utwórz miejsce docelowe powiadomień za pomocą https://your-subdomain.portpreview.dev/api/webhooks/paddle.
5. Odkryj i skopiuj sekret punktu końcowego tego miejsca docelowego do PADDLE_WEBHOOK_SECRET. To nie jest Twój klucz API.
6. Otwórz Narzędzia programistyczne → Symulacje, wybierz pojedyncze wydarzenie lub scenariusz, wybierz miejsce docelowe, skonfiguruj je i uruchom.
7. Porównaj odpowiedź symulacji Paddle z lokalnymi dziennikami i utrwalonym potwierdzeniem elementu webhook.

W całym procesie korzystaj z zasobów i danych uwierzytelniających piaskownicy. Mieszanie tajnego sekretu miejsca docelowego na żywo z żądaniem symulatora piaskownicy gwarantuje błąd podpisu, nawet jeśli oba ciągi wyglądają wiarygodnie.

Sprawdź Paddle-Signature chodnikowiec

Paddle podpisuje każdy webhook kluczem tajnym należącym do miejsca docelowego powiadomienia. Nagłówek zawiera komponenty, w tym uniksowy znacznik czasu identyfikowany przez ts oraz jeden lub więcej podpisów identyfikowanych przez h1. Paddle może dodać wersje podpisów, więc analizuj nagłówek, zamiast zakładać, że zawiera on jeden goły skrót.

Podpisany ładunek to znacznik czasu, dwukropek i nietknięta treść żądania. Paddle stosuje HMAC-SHA256 z tajnym punktem końcowym. Jego dokumentacja weryfikacji podpisu zaleca oficjalny pakiet SDK, jeśli jest dostępny, i dokumentuje algorytm ręczny. Zawsze wymuszaj tolerancję znacznika czasu pakietu SDK lub wyraźną tolerancję w weryfikatorze, aby ograniczyć ataki polegające na odtwarzaniu.

Preferuj oficjalny pakiet SDK w 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);

Uchwyt express.raw() przed jakimkolwiek globalem express.json() oprogramowanie pośredniczące dla tej trasy. W środowisku typu Fetch, takim jak Next.js App Router, użyj await request.text() raz i przekaż dokładnie ten ciąg do zestawu SDK. Urzędnik Szybki start webhooka demonstruje to zapotrzebowanie na surowe ciało.

Co musi zrobić weryfikacja ręczna

1. Przeczytaj surową treść bez normalizacji JSON.
2. Analizuj każdy komponent nagłówka oddzielonego średnikami i zbieraj obsługiwane h1 wartości.
3. Odrzuć brakujący, zniekształcony lub nieracjonalnie stary ts.
4. Obliczać HMAC_SHA256(secret, ts + ':' + rawBody).
5. Porównaj oczekiwane podsumowanie z podpisami kandydatów, korzystając z porównania bezpiecznego pod względem czasowym.
6. Dopiero po dopasowaniu przeanalizuj JSON i wyślij dalej event_type.

Akceptowanie wszelkich ważnych obsługiwanych podpisów ma znaczenie podczas rotacji sekretów, gdy może być obecny więcej niż jeden podpis. Nie dziel nagłówka i bierz na ślepo drugi element. Podczas diagnozowania niezgodności nie rejestruj tajnego punktu końcowego ani nie uzupełniaj ładunku klienta.

Projektuj symulacje wokół niezmienników rozliczeniowych

Tworzenie subskrypcji

Uruchom scenariusz tworzenia subskrypcji i sprawdź, czy baza danych może odbierać powiązane zdarzenia transakcji i subskrypcji bez przyjmowania jednej kolejności przybycia do sieci. Przechowuj identyfikatory jednostek Paddle i aktualizuj rekordy idempotentnie. Wniosek powinien przyznać dokładnie jedno uprawnienie nawet w przypadku ponownego przesłania wniosku.

Odnowienie i niepowodzenie płatności

Skorzystaj ze ścieżek pomyślnego odnowienia, przeterminowania i odzyskiwania dostępnych w konfiguracji scenariusza. Oddziel status rozliczeniowy od zasad dostępu do produktów: okres karencji może celowo utrzymać aktywny dostęp, podczas gdy Paddle zgłosi problem z windykacją.

Anulowanie i zaplanowane zmiany

Rozróżnij subskrypcję zaplanowaną do anulowania od subskrypcji, która została skutecznie anulowana. Utrzymywać next_billed_at, dane dotyczące zaplanowanych zmian i status dostawcy, zamiast zwijać cykl życia is_active.

Aktualizacje jednostek

Symuluj aktualizacje produktów, cen, klientów i subskrypcji zużywane przez pamięć podręczną. Procedura obsługi powinna bezpiecznie ignorować nieznane typy zdarzeń i potwierdzać je, jeśli podpis jest ważny; przyszłe dodatki Paddle nie powinny prowadzić do niekończącej się pętli błędów.

Idempotencja i porządkowanie przy każdym uruchomieniu

Użyj stabilnego identyfikatora zdarzenia webhook jako unikalnego klucza w tabeli paragonów. W jednej transakcji wstaw paragon, zastosuj zmianę stanu i kolejkuj efekty uboczne. Jeśli wstawianie powoduje konflikt, zwróć sukces bez powtarzania pracy. Nie wykonuj deduplikacji tylko według identyfikatora jednostki, ponieważ wiele prawidłowych aktualizacji może być ukierunkowanych na jedną subskrypcję.

Wydarzenia mogą pojawić się poza kolejnością. Porównaj czas wystąpienia zdarzenia lub pobierz najnowszą jednostkę Paddle przed zastosowaniem destrukcyjnego przejścia. Przechowuj stan i sygnaturę czasową dostawcy i odrzucaj starszą aktualizację, która zastąpiłaby nowszą. Scenariusze symulacyjne są idealne do testowania tych założeń, ponieważ tworzą połączone sekwencje, a nie izolowane urządzenia.

Rozwiązywanie problemów z błędami połączenia symulatora z hostem lokalnym

Miejsce docelowe zwraca 404 lub 405

Sprawdź, czy publiczny adres URL zawiera pełną trasę i czy trasa eksportuje POST. GET przeglądarki nie jest prawidłowym testem webhooka obsługującego tylko POST. Używać curl -X POST względem publicznego adresu URL, aby odróżnić routing tunelu od konfiguracji Paddle.

Miejsce docelowe zwraca 400

Sprawdź, czy Paddle-Signature przybył i potwierdź, że sekret punktu końcowego należy do wybranego miejsca docelowego powiadomienia. Upewnij się, że żaden analizator treści, rejestrator żądań ani oprogramowanie pośredniczące nie zużyły ani nie przeformatowały treści. Symulator wysyła weryfikowalne podpisy, zgodnie z dokumentacją w Przewodnik po symulacji Paddle'a.

Miejsce docelowe zwraca 500 lub przekroczono limit czasu

Działaj szybko i przenoś pocztę e-mail, udostępnianie i wychodzące wywołania API do kolejki. Zwrot 2xx po trwałej akceptacji. Zgłaszanie nieznanego typu zdarzenia jest częstą przyczyną niepotrzebnych awarii; użyj domyślnej gałęzi, która rejestruje i potwierdza to.

Scenariusz wykorzystuje nieoczekiwane dane

Sprawdź, czy symulacja wykorzystuje automatycznie wygenerowane wartości, czy też jest wypełniona prawdziwymi elementami piaskownicy. Sprawdź skonfigurowane opcje scenariusza i ładunek zdarzenia uruchomienia, zamiast zakładać, że odzwierciedla on poprzedni przebieg.

Lista kontrolna bezpieczeństwa przed produkcją

• Trzymaj klucze API i tajne miejsca docelowe powiadomień osobno i tylko na serwerze.
• Przed przetworzeniem sprawdź surową treść, podpis nagłówka i sygnaturę czasową.
• Użyj bezpiecznego porównania czasowego lub oficjalnego weryfikatora SDK.
• Deduplikuj identyfikatory zdarzeń i obsługuj aktualizacje poza kolejnością.
• Zastosuj limity treści, routing tylko POST, zredagowane rejestrowanie i kontrolę szybkości.
• Użyj różnych miejsc docelowych w piaskownicy i na żywo, a następnie powtórz symulacje i rzeczywiste przepływy w piaskownicy przed zmianą produkcyjnego adresu URL.

Symulator udowadnia integrację w kontrolowanych sekwencjach cyklu życia; prawdziwa kasa w piaskownicy dodatkowo potwierdza relacje kasa-jednostka. Użyj obu, a następnie przejrzyj ogólne przewodnik po podpisach webhooków I przewodnik po idempotencji przed startem.