Para probar los webhooks de la zona de pruebas de PayPal en localhost, ejecute su escucha localmente, exponga su ruta a través de un túnel HTTPS público, registre esa URL en una aplicación de la zona de pruebas y active una transacción real de la zona de pruebas o un evento simulado en el Simulador de Webhooks de PayPal. Mantenga la verificación de firma habilitada: los eventos del simulador y los eventos de la zona de pruebas asociados a la aplicación tienen una importante diferencia de verificación explicada abajo.
Por qué PayPal no puede enviar directamente a localhost
PayPal entrega notificaciones de webhooks desde sus propios servidores. Una dirección como http://localhost:3000/api/paypal apunta a la máquina de PayPal desde la perspectiva de PayPal, no la suya. Un túnel localhost le da al proceso local una dirección HTTPS pública mientras deja la aplicación en su computadora.
La documentación oficial PayPal Webhooks Simulator dice que su escucha debe ser accesible a través de HTTPS en el puerto 443. Un túnel maneja ese punto final TLS público y reenvía la solicitud a cualquier puerto local, como 3000 o 8080.
Elija la ruta de prueba de PayPal correcta
Eventos simulados de simulador para el desarrollo de oyentes
El simulador puede enviar eventos representativos, incluidas capturas de pagos, reembolsos y eventos de facturación, sin crear una transacción. Esta es la forma más rápida de confirmar el enrutamiento, el análisis JSON, los códigos de respuesta y el envío de eventos. Los eventos simulados no están vinculados a una aplicación REST, no aparecen en el visor de eventos del webhook de la aplicación, no se pueden reenviar y no representan transacciones reales.
Eventos reales de sandbox para comportamiento de un extremo a otro
Para una integración realista, cree una aplicación REST en el Panel de desarrollador de PayPal, agregue el punto final del túnel como un webhook, seleccione los tipos de eventos requeridos y complete una operación de pago o API en la zona de pruebas. Esos eventos pertenecen a la aplicación sandbox y utilizan las mismas credenciales de aplicación, ID de webhook, visor de eventos y flujo de trabajo de reenvío que utilizará antes de la producción.
Configurar un webhook de PayPal en localhost
- Inicie su aplicación y confirme que la ruta funciona localmente:
curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'. - Ejecute
npx portpreview 3000y copie la URL HTTPS generada. - Crea la devolución de llamada completa, por ejemplo
https://your-subdomain.portpreview.dev/api/webhooks/paypal. - Para pruebas simuladas, péguelo en el Simulador de Webhooks y seleccione un evento. Para probar la aplicación, agréguela en la configuración del webhook de su aplicación REST sandbox.
- Envíe un evento e inspeccione el método entrante, los encabezados de PayPal, el cuerpo sin formato, los registros del controlador y la respuesta HTTP.
Suscríbete solo a los eventos que maneja tu aplicación. Una suscripción amplia genera ruido y facilita la ejecución accidental de lógica empresarial para un evento que nunca modeló.
A practical Express listener
import express from 'express';
const app = express();
app.use(express.json({ verify: (req, _res, buf) => {
req.rawBody = Buffer.from(buf);
}}));
app.post('/api/webhooks/paypal', async (req, res) => {
const event = req.body;
// Verify first; do not fulfill an order from untrusted JSON.
const verified = await verifyPayPal(req.headers, event);
if (!verified) return res.status(401).send('invalid signature');
// Claim the event ID atomically so retries cannot duplicate work.
const firstDelivery = await claimEvent(event.id);
if (!firstDelivery) return res.sendStatus(200);
if (event.event_type === 'PAYMENT.CAPTURE.COMPLETED') {
await markOrderPaid(event.resource.id);
}
return res.sendStatus(200);
});
app.listen(3000);Mantenga el trabajo de reconocimiento breve. Almacene el evento, devuelva una respuesta 2xx y realice correos electrónicos lentos o trabajos de cumplimiento en una cola. El ID del evento es la clave de idempotencia natural; imponer una restricción de base de datos única en lugar de depender de un conjunto en memoria.
Verificar las firmas de PayPal correctamente
PayPal envía metadatos de transmisión en encabezados que incluyen PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG y PAYPAL-TRANSMISSION-TIME. Para eventos asociados a aplicaciones, puede enviar esos valores, el ID del webhook y el evento a la API de sandbox /v1/notifications/verify-webhook-signature. Una respuesta HTTP exitosa no es suficiente; requiere que verification_status sea igual a SUCCESS. PayPal también documenta la verificación criptográfica local en su guía de integración de webhook.
Advertencia sobre el simulador: El punto final de verificación de devolución de datos de PayPal no admite eventos simulados de simulador. PayPal documenta el ID literal del webhook WEBHOOK_ID para autoverificar la firma del simulador. No confunda ese valor especial con el ID de webhook real asignado a una aplicación sandbox. Si su objetivo inmediato es probar la API de devolución de datos, genere una transacción real en el espacio aislado en lugar de un evento simulado de simulador.
Valide que cualquier URL de certificado siga las reglas documentadas de PayPal antes de descargarlo, conserve la representación exacta del evento requerida por el método de verificación y nunca registre tokens de acceso, secretos de clientes, firmas ni cargas útiles de pago completas.
Prueba los eventos que cambian dinero o acceden
PAYMENT.CAPTURE.COMPLETED: otorgar cumplimiento solo después de verificar los identificadores de pedido esperados, el monto, la moneda y el estado de captura.PAYMENT.CAPTURE.REFUNDED: revertir derechos de forma segura y admitir reembolsos parciales.- Eventos de orden de pago: distingue la aprobación de una captura completa; la aprobación por sí sola no es prueba de que se capturaron fondos.
- Eventos de suscripción: activación de prueba, suspensión, cancelación, pago fallido y entrega fuera de orden en su máquina de estado de facturación.
Los eventos del proveedor son notificaciones, no comandos incuestionables de la base de datos. Para transiciones confidenciales, recupere el recurso de PayPal al que se hace referencia con credenciales API autenticadas y compárelo con su propio registro de pedido.
Solucionar problemas de entregas locales fallidas
El simulador no puede conectarse
Confirme que la URL comienza con https://, incluye la ruta exacta del webhook y aún apunta a un túnel en ejecución. Pruebe usted mismo la URL pública con curl. Un 404 generalmente significa que la ruta o ruta marco es incorrecta; un 502 generalmente significa que el túnel no puede llegar al proceso local.
El controlador devuelve 401
Primero determine si el evento provino del simulador o de una aplicación sandbox registrada. Verifique el ID del webhook y el método de verificación correspondiente. Luego verifique que los servidores proxy hayan conservado todos los encabezados PAYPAL-* y que no esté mezclando credenciales activas con api-m.sandbox.paypal.com.
PayPal reintenta o marca la entrega como fallida
Devuelve un 2xx solo después de que el evento haya sido aceptado de forma duradera. Evite redirecciones, páginas de error HTML, middleware de autenticación y trabajos sincrónicos prolongados en la ruta. Utilice el visor de eventos para eventos de aplicaciones reales y el resultado del simulador para diagnósticos de entrega simulados. Consulte la guía de reintento e idempotencia para conocer patrones de procesamiento duraderos.
Lista de verificación de seguridad antes de entrar en funcionamiento
- Utilice credenciales independientes de zona de pruebas y de cliente activo, ID de webhook y secretos de punto final.
- Verifique cada firma antes de analizar campos comerciales o cambiar de estado.
- Deduplicar mediante ID de evento de PayPal y hacer que las transacciones de cumplimiento sean atómicas.
- Permitir solo
POST, limitar el tamaño de la solicitud, aplicar límites de velocidad y mantener privada la URL del túnel cuando sea posible. - Redactar datos y credenciales del comprador de los registros; gire todo lo expuesto durante la depuración.
- Reemplace la URL del túnel temporal con un punto final de producción estable y repita las pruebas de firma y reintento.
Para obtener los esquemas completos de eventos y verificación, utilice la referencia principal de la API Webhooks de PayPal. Para obtener detalles independientes del marco sobre cuerpos sin procesar y comparaciones seguras, lea la webhook guía de verificación de firmas.