Lokalne testowanie webhooków Polar za pomocą Polar CLI

Aby lokalnie przetestować webhooki Polar, uruchom moduł obsługi webhook, zainstaluj i uwierzytelnij Polar CLI, a następnie użyj polar listen http://localhost:3000/api/webhooks/polar do przekazywania podpisanych zdarzeń bezpośrednio do komputera. Skopiuj tymczasowy sekret wydrukowany przez słuchacza do POLAR_WEBHOOK_SECRET, zweryfikuj surową treść przed jej przetworzeniem i wywołaj zdarzenie kasy, zamówienia, zwrotu kosztów lub subskrypcji w piaskownicy.

Dlaczego Polar CLI to najprostszy lokalny przepływ pracy

Normalny punkt końcowy webhooka produkcyjnego musi być publicznie dostępny za pośrednictwem protokołu HTTPS. Polar oferuje specjalnie zbudowany lokalny odbiornik, dzięki czemu nie musisz tworzyć stałego punktu końcowego ani wielokrotnie wklejać tymczasowych adresów URL wywołań zwrotnych do pulpitu nawigacyjnego. Interfejs CLI łączy się z Twoją organizacją, wyświetla sekret podpisywania sesji, odbiera zdarzenia i przekazuje je na podany lokalny adres URL.

Urzędnik Polar lokalna dokumentacja webhooka wykorzystuje polar listen http://localhost:3000/. Wskaż pełną ścieżkę, gdy aplikacja obsługuje elementy webhook poniżej trasy, takiej jak /api/webhooks/polar. Wychwytuje to błędy ścieżki przed rozpoczęciem produkcji i utrzymuje tę samą procedurę obsługi aplikacji, którą zamierzasz wdrożyć.

Zainstaluj CLI i zacznij słuchać

1. Uruchom aplikację i potwierdź, że trasa POST jest dostępna lokalnie.
2. Zainstaluj Polar CLI za pomocą polecenia z oficjalnej dokumentacji.
3. Biegnij polar login i autoryzuj właściwe konto.
4. Zacznij polar listen http://localhost:3000/api/webhooks/polar.
5. Wybierz organizację będącą właścicielem produktów piaskownicy.
6. Skopiuj wyświetlony sekret sesji do POLAR_WEBHOOK_SECRET i zrestartuj aplikację, jeśli jej środowisko jest ładowane tylko podczas uruchamiania.
7. Uruchom akcję piaskownicy i porównaj stan dostarczania CLI z lokalnymi dziennikami.

Sekret słuchacza jest częścią sesji lokalnej. Nie zakładaj, że jest to sekret punktu końcowego pulpitu nawigacyjnego ani nie używaj ponownie wartości produkcyjnej. Jeśli ponownie się połączysz i otrzymasz inny sekret, zaktualizuj środowisko lokalne przed ponownym testowaniem.

Utwórz procedurę obsługi routera aplikacji Next.js

Polar stosuje się do specyfikacji standardowych webhooków. Dostawa obejmuje webhook-id, webhook-timestamp, i webhook-signature. Weryfikacja musi używać dokładnie nieprzetworzonej treści żądania; dzwonienie request.json() najpierw i ponowna serializacja obiektu może zmienić podpisane bajty.

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

Polarny dokumentacja dostawy wywołuje typową pułapkę niestandardowej weryfikacji: standardowe biblioteki webhooks oczekują sekretu zakodowanego w formacie Base64, podczas gdy Polar zapewnia normalny ciąg tajny. Pomocnicy Polar SDK automatycznie obsługują tę konwersję. Podczas używania standardwebhooks bezpośrednio, kodowanie Base64 pełnego sekretu Polar, jak pokazano powyżej.

Preferuj oficjalny adapter frameworka, jeśli jest dostępny

Polar publikuje adaptery, które łączą weryfikację podpisu z obsługą wpisywanych ładunków. Urzędnik Ekspresowa dokumentacja adaptera zapewnia szczegółowe wywołania zwrotne dotyczące zdarzeń związanych z realizacją transakcji, zamówieniem, zwrotem kosztów, korzyściami i subskrypcją. Adapter zmniejsza ryzyko nieprawidłowego wdrożenia analizy nagłówka lub kodowania tajnego.

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

Postępuj zgodnie z udokumentowaną kolejnością oprogramowania pośredniego adaptera dla instalowanej wersji. Jeśli zamiast tego użyjesz ogólnego weryfikatora, zachowaj jawnie surową treść. Nie mieszaj adaptera odczytującego strumień z oprogramowaniem pośredniczącym, które zużywa go jako pierwsze.

Które zjawiska polarne powinieneś przetestować?

Wydarzenia w kasie

Zdarzenia przy kasie pomagają śledzić sesję, zanim stanie się ona opłaconym zamówieniem. Testuj pomyślne zakończenie oraz stany porzucone lub zaktualizowane bez udzielania dostępu tylko dlatego, że utworzono kasę. Opłacone zamówienie lub aktywna subskrypcja powinny pozostać wiarygodnym sygnałem uprawniającym.

Zamówienie opłacone i zwrócone

W przypadku wydarzenia płatnego za zamówienie przypisz klienta i produkt Polar do swojego konta wewnętrznego, a następnie przyznaj zakupioną korzyść dokładnie raz. Zdarzenia związane ze zwrotem środków powinny cofnąć jedynie uprawnienie, którego to dotyczy, zgodnie z polityką zwrotów. Przechowuj identyfikatory dostawców, aby obsługa mogła pogodzić wydarzenie z Polar.

Zdarzenia cyklu życia subskrypcji

Tworzenie testów, aktywacja, aktualizacje, anulowanie, unieważnianie i wszelkie przeterminowane zachowania obsługiwane przez Twój produkt. Żądanie anulowania nie musi oznaczać natychmiastowego zakończenia dostępu. Przechowuj status i daty obowiązywania zamiast ograniczać cykl życia do jednego is_active flaga.

Dotacje na świadczenia

Jeśli Twoja integracja korzysta z korzyści Polar, przetestuj tworzenie, aktualizację i cofanie dotacji niezależnie od zdarzeń rozliczeniowych. Spraw, aby procedury obsługi zbiegały się w pożądanym stanie, więc dwukrotne otrzymanie tego samego przydziału nie zapewni zduplikowanych zasobów.

Spraw, aby każde zdarzenie było idempotentne

Dostawa sieciowa nie jest transakcją jednorazową. Procedura obsługi może zatwierdzić pracę w bazie danych i utracić odpowiedź, powodując ponowienie próby przez nadawcę. Użyj webhook-id jako unikalny klucz dostawy i odbierz go w tej samej transakcji, która aktualizuje stan Twojej aplikacji.

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

Zwróć odpowiedź 2xx dla duplikatu, który został już ukończony. Nie wykonuj deduplikacji tylko według identyfikatora klienta lub subskrypcji, ponieważ wiele uzasadnionych zdarzeń jest skierowanych do tego samego zasobu. The przewodnik dotyczący ponawiania prób webhooka i idempotencji omawia bardziej szczegółowo wzorce skrzynek odbiorczych i nadawczych.

Staraj się, aby potwierdzenie było krótkie

Zweryfikuj żądanie, utrwal je lub umieść w kolejce trwałe zadanie i zwróć sukces. Poczta e-mail, generowanie licencji, dostęp do repozytorium, analizy i wywołania API innych firm powinny działać asynchronicznie. Szybkie potwierdzenie ogranicza liczbę ponownych prób, a trwały zapis zapobiega zniknięciu zdarzeń, jeśli proces zakończy się po powrocie.

Nieznane typy zdarzeń należy odnotować i potwierdzić po weryfikacji prawidłowego podpisu. Polar może z czasem dodawać typy wydarzeń; dodanie każdej nieznanej wartości powoduje, że nieszkodliwe dodanie schematu powoduje powtarzające się błędy w dostarczaniu.

Rozwiązywanie problemów z awariami lokalnego hosta webhooka Polar

CLI łączy się, ale trasa zwraca 404

Przejdź pełną trasę lokalną do polar listennie tylko portu. W Next.js App Router upewnij się, że plik ma nazwę route.ts i eksport POST. Przeglądarka GET zwracająca 404 nie dowodzi, że brakuje trasy POST, więc przetestuj za pomocą curl -X POST.

Każde żądanie zwraca 403

Potwierdź, że aplikacja załadowała klucz tajny wydrukowany przez bieżącą sesję CLI. Zachowaj surową treść i wszystkie trzy standardowe nagłówki webhooks. Jeśli używasz biblioteki ogólnej, zakoduj klucz Polar dokładnie raz w formacie Base64; jeśli używasz pomocnika Polar SDK, przekaż oryginalny sekret i pozwól SDK zająć się kodowaniem.

Po dokonaniu płatności nie pojawia się żadne wydarzenie

Sprawdź, czy interfejs CLI jest podłączony do tej samej organizacji i środowiska, w którym wystąpiło działanie. Pozostaw terminal nasłuchujący otwarty, korzystaj z zasobów piaskownicy i potwierdź, że Twoje działanie faktycznie osiąga stan zdarzenia, który subskrybowałeś.

Zdarzenia są przetwarzane dwukrotnie

Dodaj unikalne ograniczenie dla webhook-id i zwróć sukces w przypadku duplikatów. Sprawdź, czy po aktualizacji stanu, ale przed odpowiedzią, występuje wyjątek. Przenieś powolne efekty uboczne do procesu roboczego wspieranego przez skrzynkę nadawczą.

Stare przechwycone żądanie nie przeszło weryfikacji

Standardowa weryfikacja webhooków obejmuje sygnaturę czasową, aby ograniczyć ataki polegające na ponownym odtwarzaniu. Stary przechwyt powinien nie przejść normalnego okna weryfikacji. W przypadku testów logiki biznesowej zweryfikuj raz nową dostawę i zapisz oczyszczone urządzenie ładunku za granicą uwierzytelniania.

Lista kontrolna bezpieczeństwa przed produkcją

• Użyj oddzielnych wpisów tajnych lokalnego, piaskownicy i produkcyjnego punktu końcowego.
• Przed przetworzeniem sprawdź surową treść, znacznik czasu, identyfikator dostawy i podpis.
• Przechowuj tokeny API i sekrety elementu webhook w zmiennych środowiskowych dostępnych tylko na serwerze.
• Deduplikuj przez webhook-id i weryfikuj identyfikatory produktu, organizacji i klienta.
• Redaguj wiadomości e-mail klientów, dane rozliczeniowe, metadane i pełne ładunki z udostępnionych dzienników.
• Stosuj limity wielkości żądań i monitoruj powtarzające się nieprawidłowe podpisy.
• Zastąp lokalny odbiornik stabilnym punktem końcowym HTTPS i przetestuj nowy przepływ w piaskownicy przed włączeniem aktywnych produktów.

Interfejs CLI Polar usuwa pętlę wdrażania, ale nie powinien usuwać kontroli produkcji. Włącz weryfikację podpisu, idempotencję, filtrowanie zdarzeń i trwałe przetwarzanie lokalnie, aby testowany kod był kodem, który wysyłasz. Aby uzyskać szczegółowe informacje na temat weryfikacji niezależnej od platformy, przeczytaj przewodnik weryfikacji podpisu webhooka i generał lokalny proces debugowania.