Polar-Webhooks lokal mit der Polar CLI testen

Um Polar-Webhooks lokal zu testen, führen Sie Ihren Webhook-Handler aus, installieren und authentifizieren Sie die Polar-CLI und verwenden Sie sie dann polar listen http://localhost:3000/api/webhooks/polar um signierte Ereignisse direkt an Ihren Computer weiterzuleiten. Kopieren Sie das vom Hörer gedruckte temporäre Geheimnis in POLAR_WEBHOOK_SECRET, überprüfen Sie den Rohkörper, bevor Sie ihn verarbeiten, und lösen Sie ein Sandbox-Kauf-, Bestell-, Rückerstattungs- oder Abonnementereignis aus.

Warum die Polar CLI der einfachste lokale Workflow ist

Ein normaler Produktions-Webhook-Endpunkt muss über HTTPS öffentlich erreichbar sein. Polar bietet einen speziell entwickelten lokalen Listener, sodass Sie keinen permanenten Endpunkt erstellen oder wiederholt temporäre Rückruf-URLs in ein Dashboard einfügen müssen. Die CLI stellt eine Verbindung zu Ihrer Organisation her, zeigt ein Sitzungssignaturgeheimnis an, empfängt Ereignisse und leitet sie an die von Ihnen angegebene lokale URL weiter.

Polars Beamter Lokale Webhook-Dokumentation verwendet polar listen http://localhost:3000/. Zeigen Sie auf den vollständigen Pfad, wenn Ihre Anwendung Webhooks unterhalb einer Route verarbeitet, z. B /api/webhooks/polar. Dies erkennt Pfadfehler vor der Produktion und behält den gleichen Anwendungshandler bei, den Sie bereitstellen möchten.

Installieren Sie die CLI und beginnen Sie mit dem Zuhören

1. Starten Sie Ihre Anwendung und bestätigen Sie, dass die POST-Route lokal verfügbar ist.
2. Installieren Sie die Polar CLI mit dem Befehl aus der offiziellen Dokumentation.
3. Lauf polar login und autorisieren Sie das richtige Konto.
4. Starten polar listen http://localhost:3000/api/webhooks/polar.
5. Wählen Sie die Organisation aus, die Ihre Sandbox-Produkte besitzt.
6. Kopieren Sie das angezeigte Sitzungsgeheimnis in POLAR_WEBHOOK_SECRET und starten Sie Ihre App neu, wenn ihre Umgebung nur beim Start geladen wird.
7. Lösen Sie eine Sandbox-Aktion aus und vergleichen Sie den CLI-Lieferstatus mit Ihren lokalen Protokollen.

Das Listener-Geheimnis ist Teil der lokalen Sitzung. Gehen Sie nicht davon aus, dass es sich um ein Dashboard-Endpunktgeheimnis handelt, und verwenden Sie keinen Produktionswert wieder. Wenn Sie die Verbindung wiederherstellen und ein anderes Geheimnis erhalten, aktualisieren Sie die lokale Umgebung, bevor Sie den Test erneut durchführen.

Erstellen Sie einen Next.js App Router-Handler

Polar folgt der Standard-Webhooks-Spezifikation. Eine Lieferung beinhaltet webhook-id, webhook-timestamp, und webhook-signature. Bei der Überprüfung muss der exakte rohe Anforderungstext verwendet werden. anrufen request.json() Zuerst kann das Serialisieren des Objekts die vorzeichenbehafteten Bytes ändern.

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

Polars Lieferdokumentation weist auf eine häufige Falle bei der benutzerdefinierten Überprüfung hin: Standard-Webhooks-Bibliotheken erwarten ein Base64-codiertes Geheimnis, während Polar eine normale geheime Zeichenfolge bereitstellt. Polar SDK-Helfer führen diese Konvertierung automatisch durch. Bei der Verwendung standardwebhooks direkt Base64-kodieren Sie das komplette Polar-Geheimnis wie oben gezeigt.

Bevorzugen Sie einen offiziellen Framework-Adapter, sofern verfügbar

Polar veröffentlicht Adapter, die die Signaturüberprüfung mit typisierten Payload-Handlern kombinieren. Der Beamte Dokumentation zum Express-Adapter Bietet detaillierte Rückrufe für Checkout-, Bestell-, Rückerstattungs-, Vorteils- und Abonnementereignisse. Ein Adapter verringert die Wahrscheinlichkeit, dass das Header-Parsing oder die geheime Codierung falsch implementiert wird.

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

Befolgen Sie die dokumentierte Middleware-Reihenfolge des Adapters für die von Ihnen installierte Version. Wenn Sie stattdessen einen generischen Prüfer verwenden, behalten Sie den Rohkörper explizit bei. Mischen Sie keinen Adapter, der den Stream liest, mit Middleware, die ihn zuerst konsumiert.

Welche Polar-Events sollten Sie testen?

Kassenereignisse

Checkout-Ereignisse helfen dabei, eine Sitzung zu verfolgen, bevor daraus eine bezahlte Bestellung wird. Testen Sie den erfolgreichen Abschluss sowie den Status „Abgebrochen“ oder „Aktualisiert“, ohne Zugriff zu gewähren, nur weil ein Checkout erstellt wurde. Die bezahlte Bestellung oder das aktive Abonnement sollte das maßgebliche Berechtigungssignal bleiben.

Bestellung bezahlt und erstattet

Ordnen Sie bei einem Event mit kostenpflichtiger Bestellung den Polar-Kunden und das Produkt Ihrem internen Konto zu und gewähren Sie dann den gekauften Vorteil genau einmal. Rückerstattungsereignisse sollten gemäß Ihrer Rückerstattungsrichtlinie nur den betroffenen Anspruch rückgängig machen. Speichern Sie Anbieter-IDs, damit der Support das Ereignis mit Polar abgleichen kann.

Ereignisse im Abonnementlebenszyklus

Testen Sie die Erstellung, Aktivierung, Aktualisierung, Stornierung, Widerrufung und alle von Ihrem Produkt unterstützten überfälligen Verhaltensweisen. Eine Stornierungsanfrage bedeutet möglicherweise nicht, dass der Zugriff sofort endet. Speichern Sie Status und Gültigkeitsdaten, anstatt den Lebenszyklus auf einen zu reduzieren is_active Flagge.

Leistungszuschüsse

Wenn Ihre Integration Polar-Vorteile nutzt, testen Sie die Erstellung, Aktualisierung und den Widerruf von Zuschüssen unabhängig von Abrechnungsereignissen. Sorgen Sie dafür, dass die Handler auf den gewünschten Status konvergieren, sodass der doppelte Erhalt derselben Bewilligung nicht zur Bereitstellung doppelter Ressourcen führt.

Machen Sie jedes Ereignis idempotent

Die Netzwerkzustellung ist keine genau einmalige Transaktion. Ein Handler kann seine Datenbankarbeit festschreiben und die Antwort verlieren, was dazu führt, dass der Absender es erneut versucht. Benutzen webhook-id als eindeutigen Übermittlungsschlüssel und fordern Sie ihn in derselben Transaktion an, die Ihren Anwendungsstatus aktualisiert.

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

Geben Sie eine 2xx-Antwort für ein Duplikat zurück, das bereits abgeschlossen wurde. Deduplizieren Sie nicht nur nach Kunden- oder Abonnement-ID, da viele legitime Ereignisse auf dieselbe Ressource abzielen. Die Webhook-Wiederholungs- und Idempotenz-Leitfaden behandelt Posteingangs- und Postausgangsmuster detaillierter.

Halten Sie die Danksagungsarbeit kurz

Überprüfen Sie die Anfrage, behalten Sie sie bei oder stellen Sie einen dauerhaften Job in die Warteschlange und geben Sie Erfolg zurück. E-Mail, Lizenzgenerierung, Repository-Zugriff, Analysen und API-Aufrufe von Drittanbietern sollten asynchron laufen. Eine schnelle Bestätigung reduziert Wiederholungsversuche, während ein dauerhaftes Schreiben verhindert, dass Ereignisse verschwinden, wenn der Prozess nach der Rückkehr beendet wird.

Unbekannte Ereignistypen sollten aufgezeichnet und nach gültiger Signaturprüfung bestätigt werden. Polar kann im Laufe der Zeit Ereignistypen hinzufügen; Wenn man jeden unbekannten Wert anwendet, führt dies dazu, dass eine harmlose Schema-Ergänzung zu wiederholten Übermittlungsfehlern führt.

Beheben Sie Fehler beim Polar-Webhook-Localhost

Die CLI stellt eine Verbindung her, die Route gibt jedoch 404 zurück

Übergeben Sie die vollständige lokale Route an polar listen, nicht nur der Hafen. Stellen Sie im Next.js App Router sicher, dass die Datei benannt ist route.ts und Exporte POST. Ein Browser-GET, das 404 zurückgibt, beweist nicht, dass die POST-Route fehlt, also testen Sie es mit curl -X POST.

Jede Anfrage gibt 403 zurück

Bestätigen Sie, dass die App das von der aktuellen CLI-Sitzung gedruckte Geheimnis geladen hat. Behalten Sie den Rohkörper und alle drei Standard-Webhooks-Header bei. Wenn Sie die generische Bibliothek verwenden, kodieren Sie das Polar-Geheimnis genau einmal mit Base64. Wenn Sie einen Polar SDK-Helfer verwenden, geben Sie das ursprüngliche Geheimnis weiter und überlassen Sie die Codierung dem SDK.

Nach einem Checkout erscheint kein Ereignis

Stellen Sie sicher, dass die CLI mit derselben Organisation und Umgebung verbunden ist, in der die Aktion stattgefunden hat. Lassen Sie das Listener-Terminal geöffnet, nutzen Sie Sandbox-Ressourcen und stellen Sie sicher, dass Ihre Aktion tatsächlich den Ereignisstatus erreicht, den Sie abonniert haben.

Ereignisse werden zweimal verarbeitet

Fügen Sie eine eindeutige Einschränkung für hinzu webhook-id und Erfolg für Duplikate zurückgeben. Überprüfen Sie, ob nach Ihrer Statusaktualisierung, aber vor der Antwort eine Ausnahme auftritt. Verschieben Sie langsame Nebenwirkungen in einen vom Postausgang unterstützten Worker.

Die Überprüfung einer alten erfassten Anfrage schlägt fehl

Die Standard-Webhooks-Überprüfung umfasst einen Zeitstempel, um Replay-Angriffe einzuschränken. Eine alte Erfassung sollte das normale Überprüfungsfenster nicht bestehen. Überprüfen Sie für Geschäftslogiktests einmal eine neue Zustellung und speichern Sie eine bereinigte Nutzlastvorrichtung hinter der Authentifizierungsgrenze.

Sicherheitscheckliste vor der Produktion

• Verwenden Sie separate lokale, Sandbox- und Produktionsendpunkt-Geheimnisse.
• Überprüfen Sie vor der Verarbeitung den Rohtext, den Zeitstempel, die Zustellungs-ID und die Signatur.
• Bewahren Sie API-Tokens und Webhook-Geheimnisse in Nur-Server-Umgebungsvariablen auf.
• Deduplizieren durch webhook-id und Validierung von Produkt-, Organisations- und Kundenkennungen.
• Schwärzen Sie Kunden-E-Mails, Rechnungsdaten, Metadaten und vollständige Nutzlasten aus freigegebenen Protokollen.
• Wenden Sie Größenbeschränkungen für Anfragen an und überwachen Sie wiederholte ungültige Signaturen.
• Ersetzen Sie den lokalen Listener durch einen stabilen HTTPS-Endpunkt und testen Sie einen neuen Sandbox-Flow, bevor Sie Live-Produkte aktivieren.

Die Polar CLI entfernt die Bereitstellungsschleife, sollte jedoch keine Produktionskontrollen entfernen. Lassen Sie Signaturüberprüfung, Idempotenz, Ereignisfilterung und dauerhafte Verarbeitung lokal aktiviert, damit der Code, den Sie testen, auch der Code ist, den Sie versenden. Einzelheiten zur Framework-unabhängigen Verifizierung finden Sie im Leitfaden zur Überprüfung der Webhook-Signatur und der General Lokaler Debugging-Workflow.