Cómo usar el simulador de webhooks de Paddle en localhost

Para utilizar el simulador Paddle webhook con localhost, exponga a su manejador local a través de un túnel HTTPS, cree un destino de notificación de sandbox que apunta a la URL pública, luego ejecute una simulación de un solo evento o ciclo de vida contra ese destino. Paddle envía una solicitud realista con un Paddle-Signature encabezado, por lo que la misma ruta de verificación de cuerpos crudos puede funcionar local y en producción.

¿Por qué el simulador de Paddle es más que una carga útil de muestra

Un dispositivo JSON copiado prueba su declaración de conmutación. El simulador de Paddle prueba el destino de la red, los encabezados del proveedor, firmando secretos, estado de respuesta y esquema de eventos juntos. El funcionario webhook simulador vista general soporta eventos y escenarios únicos reutilizables. Los eventos individuales apuntan a un tipo de evento y se pueden personalizar después de una carrera. Los escenarios envían una secuencia predefinida para un ciclo de vida como creación de suscripción o renovación.

La configuración escenario puede poblar cargas de pago con las entidades Paddle existentes y variar el flujo. Cada ejecución produce registros de eventos de simulación en los que puede inspeccionar la carga útil, la solicitud de salida y la respuesta de endpoint. Eso hace que el simulador sea útil para depurar las transiciones estatales, no sólo probar que una ruta está en línea.

Conectar un endpoint local a Paddle sandbox

1. Iniciar su aplicación, por ejemplo en http://localhost:3000.
2. Añadir una ruta POST como /api/webhooks/paddle.
3. Corre npx portpreview 3000 y copiar la dirección HTTPS.
4. En Paddle sandbox, crear un destino de notificación utilizando https://your-subdomain.portpreview.dev/api/webhooks/paddle.
5. Revelar y copiar el secreto de destino en PADDLE_WEBHOOK_SECRETNo es tu clave API.
6. Abrir herramientas de desarrollo → Simulación, elegir un solo evento o escenario, seleccionar el destino, configurarlo y ejecutarlo.
7. Compare la respuesta de simulación de Paddle con sus registros locales y la recepción de Webhook persistente.

Utilice recursos de sandbox y credenciales en todo el mundo. Mixing a live destination secret with a sandbox simulator request guarantees a signature failure even though both strings look plausible.

Verificar el Paddle-Signature header

Paddle firma cada webhook con el secreto perteneciente al destino de notificación. El encabezado contiene componentes que incluyen un cronograma Unix identificado por ts y una o más firmas identificadas por h1. Paddle puede añadir versiones de firma, así que pare el encabezado en lugar de asumir que contiene un hash desnudo.

La carga útil firmada es el timetamp, un colon, y el cuerpo de solicitud intacto. Paddle aplica HMAC-SHA256 con el secreto de punto final. Es... documentación de verificación de firmas recomienda un SDK oficial donde esté disponible y documenta el algoritmo manual. Ejecute siempre la tolerancia de los tiempos del SDK o una tolerancia explícita en su verificador para limitar los ataques de repetición.

Preferir el SDK oficial en Nodo

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

Monte express.raw() ante todo el mundo express.json() Midware para esta ruta. En un marco de estilo Fetch como Next.js App Router, uso await request.text() una vez y pasar esa cuerda exacta al SDK. El funcionario webhook quickstart demuestra este requisito corporal crudo.

Qué verificación manual debe hacer

1. Lea el cuerpo crudo sin JSON normalización.
2. Parse cada componente de cabecera separada de semilón y recopilar soporte h1 valores.
3. Rechazar a un desaparecido, malformado o poco razonablemente viejo ts.
4. Computación HMAC_SHA256(secret, ts + ':' + rawBody).
5. Compare el digest esperado con firmas de candidatos usando una comparación de tiempo seguro.
6. Sólo después de un partido, parse JSON y enviar en event_type.

Aceptar cualquier asunto válido de firma apoyada durante la rotación secreta, cuando más de una firma puede estar presente. No dividir el encabezado y tomar ciegamente el segundo artículo. No inicie el endpoint secreto o complete la carga útil del cliente mientras diagnostica un desajuste.

simulaciones de diseño sobre facturación de invariantes

Creación de subscripción

Ejecute un escenario de creación de suscripción y verifique que su base de datos puede recibir eventos de transacción y suscripción relacionados sin asumir una orden de llegada de la red. Store Paddle IDs de entidad y actualiza los registros de forma idempotente. La solicitud debe conceder exactamente un derecho, incluso si una solicitud es resentida.

Fallo de renovación y pago

Ejerce caminos de renovación exitosos, pasados y recuperación disponibles en su configuración de escenario. Estado de facturación separado de la política de acceso al producto: su período de gracia puede mantener el acceso activo intencionadamente mientras Paddle reporta un problema de colección.

Cancelación y cambios programados

Destinguir una suscripción programada para cancelar de uno que ha alcanzado su cancelación efectiva. Preserve next_billed_at, datos de cambio programados y estado del proveedor en lugar de colapsar el ciclo de vida en is_active.

Actualizaciones de la Entidad

Simula el producto, precio, cliente y actualizaciones de suscripción que su caché consume. Un manejador debe ignorar los tipos de eventos desconocidos de forma segura y reconocerlos si la firma es válida; las adiciones futuras Paddle no deben convertirse en un bucle de falla interminable.

Idempotencia y pedidos en cada carrera

Utilice el ID estable del evento webhook como una clave única en una mesa de recepción. En una transacción, inserte la recepción, aplique el cambio del estado y entienda efectos secundarios. Si conflictos de inserción, devuelve el éxito sin repetir el trabajo. No deduplicar sólo por ID de entidad porque muchas actualizaciones legítimas pueden apuntar una suscripción.

Los eventos pueden salir de orden. Compare el tiempo de ocurrencia del evento o recupere la última entidad Paddle antes de aplicar una transición destructiva. Almacene el estado y el horario del proveedor, y rechace una actualización anterior que sobreescribirá una nueva. Los escenarios de simulación son ideales para probar estas suposiciones porque producen secuencias conectadas en lugar de accesorios aislados.

Troubleshoot simulator-to-localhost failures

Destino devuelve 404 o 405

Compruebe que la URL pública incluye la ruta completa y que la ruta exporta POST. Un navegador GET no es una prueba válida de un Webhook solo POST. Uso curl -X POST contra la URL pública para distinguir el enrutamiento del túnel de la configuración Paddle.

Destino devuelve 400

Inspeccione si Paddle-Signature llegado y confirmar el secreto de endpoint pertenece al destino de notificación seleccionado. Asegúrese de que ningún analizador corporal, solicite logger, o middleware consumido o reformateado el cuerpo. El simulador envía firmas verificables, como se documenta en Guía de simulación de Paddle.

Destino devuelve 500 o varias veces

Persiste rápidamente y mueve correo electrónico, provisioning y outbound API llama a una cola. Volver 2xx después de la aceptación duradera. Lanzar un tipo de evento desconocido es una causa común de fallos innecesarios; utilizar una rama predeterminada que lo registra y lo reconoce.

El escenario utiliza datos inesperados

Revise si la simulación utiliza valores generados automáticamente o está poblada con entidades de sandbox reales. Inspeccione las opciones de escenario configuradas y la carga útil del evento de ejecución en lugar de asumir que refleja una ejecución anterior.

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

• Mantenga las teclas API y los secretos de destino de notificación separados y solo servidor.
• Verifique el cuerpo crudo, la firma del encabezado, y el temporizador antes del procesamiento.
• Utilice una comparación de tiempo seguro o verificador oficial SDK.
• Deduplicar IDs de eventos y manejar actualizaciones fuera de orden.
• Aplicar límites de cuerpo, POST sólo de enrutamiento, registro redactado y controles de velocidad.
• Utilice distintos destinos de sandbox y en directo, luego repetir simulaciones y flujos reales de sandbox antes de cambiar la URL de producción.

El simulador demuestra su integración bajo secuencias controladas del ciclo de vida; una revisión real de la caja de arena también demuestra relaciones de checkout-a-entidad. Use ambos, luego revise el general webhook signature guide y idempotency guide antes del lanzamiento.