Webhooks con Node.js y Swift: Cómo procesar eventos de Stripe en tiempo real en tu App de iOS

Cobrar en una app parece sencillo: el usuario paga, la app recibe «éxito» y listo. El problema llega el día que el pago se completa pero la app se cierra, se queda sin cobertura o el usuario la mata justo en ese segundo. Has cobrado, pero tu sistema no se ha enterado.

Por eso la confirmación de verdad tiene que llegar a tu servidor, no a la app. En este artículo montamos el flujo completo con Stripe: el backend en Node.js que prepara el pago, la pasarela en Swift y los webhooks que confirman cada cobro de forma segura.

Importante antes de empezar: según la norma 3.1.1 de las App Store Review Guidelines, el contenido digital que se consume dentro de la app (suscripciones, monedas virtuales, funciones premium, niveles de un juego…) debe venderse con las compras In-App de Apple (StoreKit). Stripe es la opción adecuada para bienes físicos y servicios que se disfrutan fuera de la app: pedidos de comida, entradas, reservas, transporte o tiendas online. Si lo que vendes es contenido digital, revisa nuestra guía de compras In-App con StoreKit 2.


¿Qué es un Webhook de Stripe y por qué es vital para tu App de iOS?

Un webhook es esencialmente una llamada HTTP automatizada (un callback) enviada por un servicio externo cuando ocurre un evento específico. En el ecosistema de Stripe, cuando un usuario completa una compra, el servidor de Stripe envía una notificación HTTP POST con una carga útil JSON directamente a tu servidor backend.

Depender exclusivamente del SDK móvil para confirmar un pago presenta riesgos severos:

  • Fallas de red en el dispositivo: El cobro puede procesarse en los servidores bancarios, pero la app del usuario puede perder cobertura antes de recibir la confirmación.
  • Seguridad y fraude: Los clientes móviles pueden ser vulnerados o interceptados (ataques Man-in-the-Middle). El estado definitivo de una transacción financiera siempre debe ser validado por tu propio servidor.
  • Suscripciones y cobros asíncronos: Métodos de pago como transferencias SEPA, OXXO o renovaciones automáticas de suscripciones ocurren fuera de la app móvil. Los webhooks son el único medio para enterarte de estos cambios.

Por estas razones, el flujo profesional delega la confirmación del pedido (preparar un envío, confirmar una reserva, emitir una entrada…) a la recepción exitosa de un webhook.


La Arquitectura: El flujo de datos entre Swift, Stripe y Node.js

Para procesar pagos en tiempo real sin fisuras, el flujo de comunicación debe seguir una secuencia precisa:

  1. La app en Swift solicita a tu backend un PaymentIntent.
  2. Tu backend en Node.js crea el intento con la API de Stripe y devuelve el client_secret a la app.
  3. El SDK de Stripe en iOS presenta la interfaz de pago (PaymentSheet) y envía los datos de la tarjeta de forma cifrada a Stripe.
  4. Stripe procesa el cobro y dispara un evento payment_intent.succeeded hacia la URL pública de tu webhook.
  5. Node.js intercepta y valida la firma del evento, actualiza la base de datos (por ejemplo, marcando el pedido como «pagado») y notifica al dispositivo iOS mediante notificaciones push silenciosas (APNs) o WebSockets.

Configuración del Servidor en Node.js: Escuchando eventos de Stripe

Para recibir los eventos, utilizaremos Express y la librería oficial de stripe para Node.js. Un detalle fundamental es que Stripe requiere el cuerpo de la petición en formato crudo (raw buffer) para verificar la firma de seguridad criptográfica y evitar ataques de repetición (replay attacks).

1. Inicialización y dependencias

Instala los paquetes necesarios en tu proyecto:

npm install express stripe dotenv

2. Endpoint para preparar el pago

La app necesita tres datos para mostrar la pasarela: el client_secret del PaymentIntent, una clave efímera y el ID del cliente. Este endpoint los genera (va en el mismo server.js del paso 3, después de crear app y stripe):

// Endpoint que llama la app para preparar el pago
app.post('/payment-sheet', express.json(), async (req, res) => {
  try {
    // En producción, reutiliza el cliente de Stripe asociado a tu usuario
    const customer = await stripe.customers.create();

    const ephemeralKey = await stripe.ephemeralKeys.create(
      { customer: customer.id },
      // Usa la versión de API que indique la documentación de tu versión del SDK de iOS
      { apiVersion: process.env.STRIPE_IOS_API_VERSION }
    );

    const paymentIntent = await stripe.paymentIntents.create({
      amount: 2550, // 25,50 € en céntimos: calcula siempre el importe en el servidor
      currency: 'eur',
      customer: customer.id,
      automatic_payment_methods: { enabled: true },
      metadata: { orderId: req.body.orderId }
    });

    res.json({
      paymentIntent: paymentIntent.client_secret,
      ephemeralKey: ephemeralKey.secret,
      customer: customer.id
    });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

El importe nunca debe llegar desde la app: calcúlalo en el servidor a partir del pedido. Guardar el orderId en metadata te permitirá saber en el webhook qué pedido se ha pagado.

3. Implementación del Endpoint de Webhook

Crea tu archivo server.js asegurándote de no procesar el body como JSON estándar en la ruta del webhook:

const express = require('express');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const app = express();
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

// Middleware especial para capturar el payload en bruto
app.post('/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    // Verificación criptográfica obligatoria
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    console.error(`Error en la firma del webhook: ${err.message}`);
    return response.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Manejo de eventos específicos
  switch (event.type) {
    case 'payment_intent.succeeded': {
      const paymentIntent = event.data.object;
      console.log(`Pago exitoso para el ID: ${paymentIntent.id}`);

      // Lógica de negocio:
      // 1. Marcar el pedido como pagado en la base de datos (de forma idempotente)
      // 2. Avisar a la app con una notificación push (APNs)
      marcarPedidoPagado(paymentIntent.metadata.orderId, paymentIntent.id);
      break;
    }

    case 'payment_intent.payment_failed': {
      const failedPayment = event.data.object;
      console.warn(`Pago fallido: ${failedPayment.last_payment_error?.message}`);
      break;
    }

    default:
      console.log(`Evento no manejado: ${event.type}`);
  }

  // Responder a Stripe con 200 OK inmediatamente
  response.json({ received: true });
});

function marcarPedidoPagado(orderId, paymentIntentId) {
  // Guarda paymentIntentId para no procesar dos veces el mismo pago
  // y envía la notificación push al dispositivo del usuario
}

app.listen(3000, () => console.log('Servidor corriendo en el puerto 3000'));

Implementación en Swift: La experiencia en iOS

En la aplicación de iOS, el flujo visual se gestiona mediante el SDK StripePaymentSheet, mientras que la actualización del estado puede resolverse escuchando notificaciones remotas o actualizando el estado de la vista tras la confirmación local.

1. Instalar el SDK de Stripe en Xcode

Agrega el paquete mediante Swift Package Manager (SPM):

  • Repositorio: https://github.com/stripe/stripe-ios

2. Presentar la pasarela de pago en Swift

A continuación se muestra un ejemplo en SwiftUI para inicializar y presentar el flujo de pago:

import SwiftUI
import StripePaymentSheet

struct CheckoutView: View {
    @StateObject var viewModel = CheckoutViewModel()

    var body: some View {
        VStack(spacing: 20) {
            Text("Confirmar pedido")
                .font(.title)

            if let paymentSheet = viewModel.paymentSheet {
                PaymentSheet.PaymentButton(
                    paymentSheet: paymentSheet,
                    onCompletion: viewModel.onPaymentCompletion
                ) {
                    Text("Comprar Ahora")
                        .padding()
                        .frame(maxWidth: .infinity)
                        .background(Color.blue)
                        .foregroundColor(.white)
                        .cornerRadius(10)
                }
            } else {
                ProgressView("Cargando pasarela...")
            }
        }
        .padding()
        .onAppear {
            viewModel.preparePaymentSheet()
        }
    }
}

class CheckoutViewModel: ObservableObject {
    @Published var paymentSheet: PaymentSheet?
    @Published var paymentResult: PaymentSheetResult?

    func preparePaymentSheet() {
        // 1. Llamar a POST /payment-sheet de tu backend (APIService es tu cliente de red)
        //    para obtener customerId, ephemeralKey y paymentIntentClientSecret
        APIService.shared.fetchPaymentParams { [weak self] customer, ephemeralKey, clientSecret in
            var configuration = PaymentSheet.Configuration()
            configuration.merchantDisplayName = "Mi App iOS"
            configuration.customer = .init(id: customer, ephemeralKeySecret: ephemeralKey)

            DispatchQueue.main.async {
                self?.paymentSheet = PaymentSheet(
                    paymentIntentClientSecret: clientSecret,
                    configuration: configuration
                )
            }
        }
    }

    func onPaymentCompletion(result: PaymentSheetResult) {
        self.paymentResult = result
        switch result {
        case .completed:
            // La UI muestra éxito temporal, pero la app espera la confirmación del Webhook
            print("Pago completado localmente. Esperando sincronización del backend...")
        case .failed(let error):
            print("Error en el pago: \(error.localizedDescription)")
        case .canceled:
            print("Pago cancelado por el usuario.")
        }
    }
}

3. Sincronización en tiempo real en iOS

Una vez que el usuario ve el check de confirmación de Stripe, tu aplicación no debe dar el pedido por confirmado hasta que el servidor procese el webhook. Para reflejar esto en tiempo real en la app móvil:

  • Apple Push Notifications (APNs silenciosas): Cuando Node.js recibe payment_intent.succeeded, envía una notificación push en segundo plano (content-available: 1) a la app de iOS. La app despierta, consulta el estado del pedido y actualiza la interfaz. Ojo: iOS no garantiza la entrega de las notificaciones silenciosas, así que consulta también el estado al volver a abrir la pantalla.
  • Server-Sent Events (SSE) o WebSockets: Si el usuario permanece con la pantalla abierta, una conexión de socket abierta puede enviar una señal instantánea desde Node.js a la app (con Combine o Swift Concurrency) para mostrar el pedido como confirmado al instante.

Mejores Prácticas de Seguridad y Despliegue

Procesar pagos requiere estándares estrictos. Al desplegar esta arquitectura en producción, ten en cuenta las siguientes recomendaciones:

  • Comprobación estricta de firmas: Nunca desactives stripe.webhooks.constructEvent. Es la única barrera que previene que atacantes envíen payloads falsos a tu servidor haciéndose pasar por Stripe.
  • Idempotencia: Los webhooks de Stripe pueden enviarse más de una vez para un mismo evento si la conexión oscila. Diseña la base de datos de tu backend para que el procesamiento del evento sea idempotente (procesar el mismo evento dos veces no debe duplicar las compras).
  • Respuestas rápidas (HTTP 200): Stripe espera recibir una respuesta HTTP 200 en menos de un par de segundos. Procesa tareas pesadas (generación de facturas PDF, envíos de emails masivos) en colas de trabajo asíncronas (por ejemplo, BullMQ sobre Redis) después de responder la petición.
  • Pruebas locales con Stripe CLI: Antes de desplegar en AWS, Heroku o DigitalOcean, prueba tus webhooks localmente redirigiendo tráfico con la herramienta oficial:
    stripe listen --forward-to localhost:3000/webhook

Errores típicos que conviene evitar

  • Parsear el body antes del webhook. Si express.json() procesa la petición antes, la verificación de la firma fallará siempre.
  • No ser idempotente. Stripe puede enviar el mismo evento dos veces: guarda el ID del pago y no lo proceses de nuevo.
  • Calcular el importe en la app. El precio siempre se calcula en el servidor; si no, cualquiera podría pagar lo que quisiera.
  • Ignorar los pagos fallidos. Escucha también payment_intent.payment_failed para avisar al usuario y no dejar pedidos en el limbo.

Conclusión

La regla de oro es sencilla: la app muestra, el servidor decide. La app puede enseñar un «¡pago completado!», pero solo el webhook verificado debe marcar un pedido como pagado.

Antes de salir a producción, prueba con la Stripe CLI los casos raros: tarjetas rechazadas, pagos que requieren autenticación y webhooks repetidos. Es una hora de trabajo que te ahorra muchos disgustos con clientes y con contabilidad.

¿Prefieres partir de un backend que ya lo resuelve?

El iOS Backend Starter incluye los webhooks de Stripe tal como los explico aquí: firma verificada, idempotencia, activación de lo comprado (con avisos sobre las normas de Apple incluidos), reembolsos y push de confirmación al usuario. Viene con su app SwiftUI de ejemplo con PaymentSheet, login con Sign in with Apple y notificaciones push sin Firebase.

Ver el iOS Backend Starter

Artículos relacionados: Compras In-App en iOS con StoreKit 2: Guía de implementación rápida en SwiftUI (Sin RevenueCat) · Cómo buildear y consumir Webhooks seguros en tu Backend (PHP y Node.js) · Cómo implementar Apple Pay en tu App de Swift paso a paso (Sandbox y Configuración)

Deja una respuesta