Prueba webhooks de Polar en local con la CLI de Polar

Para probar los webhooks Polar localmente, ejecute su controlador de webhook, instale y autentique la CLI de Polar, luego use polar listen http://localhost:3000/api/webhooks/polar para transmitir eventos firmados directamente a su máquina. Copie el secreto temporal impreso por el oyente en POLAR_WEBHOOK_SECRET, verifique el cuerpo sin procesar antes de procesarlo y active un evento de pago, pedido, reembolso o suscripción en el sandbox.

Por qué Polar CLI es el flujo de trabajo local más sencillo

Un punto final de webhook de producción normal debe ser accesible públicamente a través de HTTPS. Polar ofrece un oyente local especialmente diseñado, por lo que no es necesario crear un punto final permanente ni pegar repetidamente URL de devolución de llamada temporales en un panel. La CLI se conecta a su organización, muestra un secreto de firma de sesión, recibe eventos y los reenvía a la URL local que usted proporciona.

oficial de polar documentación de webhook local usos polar listen http://localhost:3000/. Apunte a la ruta completa cuando su aplicación maneje webhooks debajo de una ruta como /api/webhooks/polar. Esto detecta errores de ruta antes de la producción y mantiene el mismo controlador de aplicaciones que desea implementar.

Instale la CLI y comience a escuchar

1. Inicie su aplicación y confirme que su ruta POST esté disponible localmente.
2. Instale Polar CLI usando el comando de la documentación oficial.
3. correr polar login y autorizar la cuenta correcta.
4. Empezar polar listen http://localhost:3000/api/webhooks/polar.
5. Seleccione la organización propietaria de sus productos sandbox.
6. Copie el secreto de sesión mostrado en POLAR_WEBHOOK_SECRET y reinicie su aplicación si su entorno se carga solo al inicio.
7. Active una acción de espacio aislado y compare el estado de entrega de la CLI con sus registros locales.

El secreto del oyente es parte de la sesión local. No asuma que equivale a un secreto de punto final del panel ni reutilice un valor de producción. Si se vuelve a conectar y recibe un secreto diferente, actualice el entorno local antes de volver a realizar la prueba.

Crear un controlador de enrutador de aplicaciones Next.js

Polar sigue la especificación de Webhooks estándar. Una entrega incluye webhook-id, webhook-timestamp, y webhook-signature. La verificación debe utilizar el cuerpo de solicitud sin formato exacto; llamando request.json() primero y serializar el objeto nuevamente puede cambiar los bytes firmados.

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

polares documentación de entrega señala una trampa común de verificación personalizada: las bibliotecas de Webhooks estándar esperan un secreto codificado en Base64, mientras que Polar proporciona una cadena secreta normal. Los asistentes del SDK de Polar manejan esta conversión automáticamente. Al usar standardwebhooks directamente, codifique en Base64 el secreto Polar completo como se muestra arriba.

Prefiere un adaptador de marco oficial cuando esté disponible

Polar publica adaptadores que combinan la verificación de firmas con controladores de carga útil tipificados. El funcionario Documentación del adaptador exprés proporciona devoluciones de llamadas granulares para eventos de pago, pedido, reembolso, beneficios y suscripción. Un adaptador reduce la posibilidad de implementar incorrectamente el análisis de encabezados o la codificación secreta.

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

Siga el orden del middleware documentado del adaptador para la versión que instale. Si utiliza un verificador genérico, conserve el cuerpo sin formato explícitamente. No mezcle un adaptador que lea la transmisión con middleware que la consuma primero.

¿Qué eventos polares deberías probar?

Eventos de pago

Los eventos de pago ayudan a realizar un seguimiento de una sesión antes de que se convierta en un pedido pagado. Pruebe la finalización exitosa y los estados abandonados o actualizados sin otorgar acceso simplemente porque se creó un pago. La orden paga o la suscripción activa deben seguir siendo la señal de derecho autorizada.

Pedido pagado y reembolsado

Para un evento de pedido pagado, asigne el cliente y el producto Polar a su cuenta interna y luego otorgue el beneficio comprado exactamente una vez. Los eventos de reembolso deben revertir únicamente el derecho afectado según su política de reembolso. Almacene los ID de los proveedores para que el soporte pueda conciliar el evento con Polar.

Eventos del ciclo de vida de la suscripción

Creación de pruebas, activación, actualizaciones, cancelación, revocación y cualquier comportamiento vencido que admita su producto. Una solicitud de cancelación no puede significar que el acceso finalice inmediatamente. Estado de la tienda y fechas de vigencia en lugar de reducir el ciclo de vida a uno is_active bandera.

Subvenciones de beneficios

Si tu integración utiliza los beneficios de Polar, prueba la creación, actualización y revocación de concesiones independientemente de los eventos de facturación. Haga que los controladores converjan en el estado deseado para que recibir la misma concesión dos veces no proporcione recursos duplicados.

Haz que cada evento sea idempotente

La entrega en red no es una transacción que se realiza exactamente una vez. Un controlador puede confirmar su trabajo de base de datos y perder la respuesta, lo que hace que el remitente vuelva a intentarlo. uso webhook-id como una clave de entrega única y reclámela en la misma transacción que actualiza el estado de su solicitud.

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

Devuelve una respuesta 2xx para un duplicado que ya se completó. No realice la deduplicación únicamente por ID de cliente o suscripción porque muchos eventos legítimos tienen como objetivo el mismo recurso. el Guía de idempotencia y reintento de webhook cubre los patrones de bandeja de entrada y salida con más detalle.

Mantenga breve el trabajo de reconocimiento

Verifique la solicitud, persista o ponga en cola un trabajo duradero y obtenga resultados exitosos. El correo electrónico, la generación de licencias, el acceso al repositorio, los análisis y las llamadas API de terceros deben ejecutarse de forma asincrónica. El reconocimiento rápido reduce los reintentos, mientras que una escritura duradera evita que los eventos desaparezcan si el proceso sale después de regresar.

Los tipos de eventos desconocidos deben registrarse y reconocerse después de una verificación de firma válida. Polar puede agregar tipos de eventos a lo largo del tiempo; Agregar cada valor desconocido convierte una adición de esquema inofensiva en fallas repetidas de entrega.

Solucionar problemas de fallas del host local del webhook Polar

La CLI se conecta pero la ruta devuelve 404

Pase la ruta local completa a polar listen, no sólo el puerto. En Next.js App Router, asegúrese de que el archivo tenga el nombre route.ts y exportaciones POST. Un navegador GET que devuelve 404 no prueba que falte la ruta POST, así que pruebe con curl -X POST.

Cada solicitud devuelve 403

Confirme que la aplicación cargó el secreto impreso por la sesión CLI actual. Conserve el cuerpo sin formato y los tres encabezados de Webhooks estándar. Si utiliza la biblioteca genérica, codifique en Base64 el secreto Polar exactamente una vez; Si utiliza un asistente Polar SDK, pase el secreto original y deje que el SDK se encargue de la codificación.

No aparece ningún evento después de realizar el pago

Verifique que la CLI esté conectada a la misma organización y entorno donde ocurrió la acción. Mantenga abierta la terminal de escucha, utilice los recursos de la zona de pruebas y confirme que su acción realmente alcance el estado de evento al que se suscribió.

Los eventos se procesan dos veces

Agregue una restricción única para webhook-id y devolver el éxito para los duplicados. Compruebe si se produce una excepción después de la actualización de su estado pero antes de la respuesta. Traslade los efectos secundarios lentos a un trabajador respaldado por la bandeja de salida.

Una solicitud capturada antigua no supera la verificación

La verificación estándar de Webhooks incluye una marca de tiempo para limitar los ataques de repetición. Una captura antigua debería fallar en la ventana de verificación normal. Para pruebas de lógica empresarial, verifique una entrega nueva una vez y guarde un elemento de carga útil desinfectado detrás del límite de autenticación.

Lista de verificación de seguridad antes de la producción.

• Utilice secretos de punto final de producción, de entorno aislado y locales separados.
• Verifique el cuerpo sin formato, la marca de tiempo, el ID de entrega y la firma antes de procesar.
• Mantenga los tokens de API y los secretos de webhooks en variables de entorno exclusivas del servidor.
• Deduplicar por webhook-id y validar identificadores de productos, organizaciones y clientes.
• Elimine el correo electrónico del cliente, los datos de facturación, los metadatos y las cargas útiles completas de los registros compartidos.
• Aplique límites de tamaño de solicitud y supervise las firmas no válidas repetidas.
• Reemplace el oyente local con un punto final HTTPS estable y pruebe un nuevo flujo de espacio aislado antes de habilitar productos activos.

La CLI de Polar elimina el bucle de implementación, pero no debería eliminar los controles de producción. Mantenga habilitados localmente la verificación de firmas, la idempotencia, el filtrado de eventos y el procesamiento duradero para que el código que pruebe sea el código que envíe. Para obtener detalles de verificación independientes del marco, lea el guía de verificación de firma de webhook y el general flujo de trabajo de depuración local.