Notificaciones push de pagos de Stripe: una alerta en el teléfono por cada venta, cobro fallido y disputa

La primera venta del día es la que quieres conocer. El cobro fallido de las 2 a. m. importa más, y una disputa tiene un plazo: si no respondes a tiempo, la pierdes. Stripe se entera de las tres cosas en el momento en que ocurren. Tú te enteras cuando vuelves a abrir el panel.
Stripe tiene sus propias notificaciones. La aplicación Stripe Dashboard para iOS y Android puede enviarte notificaciones push de pagos nuevos, clientes nuevos, pagos disputados, transferencias depositadas y un resumen diario, y el panel puede enviarte correos sobre eventos de la cuenta. Eso cubre mucho. Lo que no te da es control: no puedes elegir el texto, no puedes hacer que una factura fallida suene más que una venta, y no puedes enviar nada desde tus propios sistemas al mismo flujo. Un webhook de Stripe a Pocket Alert sí puede.
Lo que necesitas
- Una cuenta de Stripe con permiso para crear webhooks (rol Administrador o Developer).
- Una cuenta de Pocket Alert, una clave de API de Claves de API y la aplicación en tu iPhone o Android.
- Para la ruta con código: Node 20 o posterior y un lugar público donde ejecutarlo.
Nivel 1: sin código
Stripe envía cada evento como JSON, y los webhooks de Pocket Alert aceptan JSON y lo renderizan mediante una plantilla. Esa es toda la infraestructura que hace falta.
1. Crea un webhook de Pocket Alert por tipo de evento
El truco es un webhook por tipo de evento. El título de la notificación push es siempre Webhook <name>, así que el nombre decide lo que ves en la pantalla de bloqueo, y cada webhook tiene su propia prioridad predeterminada y sus botones. El plan Gratuito incluye un webhook, así que empieza con las ventas; el conjunto completo de cuatro requiere un plan de pago, que además desbloquea los botones.
Puedes crear webhooks en la consola, en Webhooks, donde se define el nombre, la plantilla y la prioridad predeterminada. Los botones de acción se configuran a través de la API, así que la forma más rápida de tenerlo todo es una llamada de curl por webhook:
export PA_KEY='YOUR_API_KEY'
curl -sS https://api.pocketalert.app/v1/webhooks \
-H "Token: $PA_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<'EOF'
{
"name": "Stripe sale",
"message": "%data.object.amount_total% %data.object.currency% from %data.object.customer_details.email% (%data.object.payment_status%)",
"default_level": 0,
"actions": "[{\"type\":\"view\",\"label\":\"Open in Stripe\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
EOF
La respuesta contiene un slug en url. Tu URL de recepción es https://p4a.me/wh/<slug>, y la consola también la muestra. actions es una cadena JSON, no un array, por eso las comillas están escapadas.
Repite con estos cuerpos para los otros tres:
{
"name": "Stripe payment failed",
"message": "%data.object.amount_due% %data.object.currency% failed for %data.object.customer_email%, attempt %data.object.attempt_count%",
"default_level": 1,
"actions": "[{\"type\":\"view\",\"label\":\"Open invoice\",\"value\":\"https://dashboard.stripe.com/invoices/%data.object.id%\"},{\"type\":\"copy\",\"label\":\"Copy pay link\",\"value\":\"%data.object.hosted_invoice_url%\"}]"
}
{
"name": "Stripe dispute",
"message": "%data.object.amount% %data.object.currency% disputed. Reason: %data.object.reason%",
"default_level": 2,
"actions": "[{\"type\":\"view\",\"label\":\"Open payment\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
{
"name": "Stripe subscription",
"message": "New %data.object.status% subscription: %data.object.items.data.0.price.unit_amount% %data.object.currency% per %data.object.items.data.0.price.recurring.interval%",
"default_level": -1,
"actions": "[{\"type\":\"view\",\"label\":\"Open subscription\",\"value\":\"https://dashboard.stripe.com/subscriptions/%data.object.id%\"}]"
}
Los niveles van de -2 (silencioso) a 2 (crítico). Un pago fallido es high, que atraviesa la Concentración en iPhone. Una disputa es critical, que suena aunque el interruptor de silencio esté activado y aunque esté activo No molestar. Las alertas críticas requieren un plan de pago; en el plan Gratuito llegan como high. Las suscripciones nuevas son low: útiles de saber, pero sin motivo para vibrar.
El botón de copiar de la notificación de pago fallido copia en el portapapeles la página de pago alojada de la factura, lista para pegar en un correo del tipo "tu tarjeta fue rechazada".
2. Añade destinos de eventos en Stripe
En el panel de Stripe, abre Workbench, ve a la pestaña Webhooks y haz clic en Create an event destination. Después:
- Elige Your account.
- Selecciona el payload Snapshot. Stripe recomienda ahora Thin para código nuevo, pero un evento thin solo incluye el ID del objeto, así que una plantilla no tiene importe ni correo que mostrar. Snapshot envía el objeto completo.
- Selecciona el evento, por ejemplo
checkout.session.completed. - Elige Webhook endpoint como tipo de destino y pega la URL
https://p4a.me/wh/...correspondiente.
Hazlo una vez por cada webhook de Pocket Alert, de modo que cada destino de Stripe envíe un tipo de evento a una URL:
| Evento de Stripe | Webhook de Pocket Alert | Título de la notificación | Nivel |
|---|---|---|---|
checkout.session.completed | Stripe sale | Webhook Stripe sale | default |
invoice.payment_failed | Stripe payment failed | Webhook Stripe payment failed | high |
charge.dispute.created | Stripe dispute | Webhook Stripe dispute | critical |
customer.subscription.created | Stripe subscription | Webhook Stripe subscription | low |
Stripe permite 16 destinos de eventos por cuenta, así que cuatro están bien.
¿Checkout o PaymentIntents? Si tus clientes pagan con Checkout o con enlaces de pago, usa checkout.session.completed. Si creas tu propio formulario de pago, usa payment_intent.succeeded en su lugar y cambia la plantilla a %data.object.amount% %data.object.currency% %data.object.receipt_email% y el botón a /payments/%data.object.id%. Suscribirte a ambos te dará dos notificaciones por venta, porque un pago de Checkout dispara los dos eventos.
3. Pruébalo
Crea un pago de prueba en un entorno sandbox, o ejecuta stripe trigger checkout.session.completed con la CLI de Stripe. Después, abre el webhook en la consola de Pocket Alert: su historial muestra cada petición que envió Stripe, con cabeceras, el cuerpo sin procesar, el mensaje renderizado y el código de estado de la respuesta. Cuando un campo sale vacío, ahí ves qué ruta era incorrecta.
Una venta llega así:
Webhook Stripe sale
4900 usd from [email protected] (paid)
[Open in Stripe]
Lo que la plantilla no puede hacer
Ten claros los límites antes de depender de ella:
- Los importes están en unidades mínimas. Stripe envía
4900para 49,00 $ y5000para ¥5000, porque el yen no tiene céntimos. La plantilla copia los valores tal cual y no puede dividir entre 100. Aprenderás a leer4900 usdrápido, pero si quieres$49.00, usa el Nivel 2. - No hay verificación de firma. Stripe firma cada petición con la cabecera
Stripe-Signature. Pocket Alert no verifica firmas de terceros; el slug aleatorio de la URL es el único secreto. Quien lo conozca puede enviarte "ventas" falsas. Para una notificación es una molestia, no una brecha, porque no se cumple ningún pedido. Mantén la URL en privado de todos modos, y usa el Nivel 2 si necesitas demostrar que una notificación procede de Stripe. - No hay condiciones. Una plantilla no puede decir "envía solo ventas de más de 500 $" o "omite el modo de prueba". El filtrado se hace en Stripe mediante los eventos que elijas, o en el código.
- Los botones del panel apuntan al modo en vivo. Los objetos de prueba viven en
dashboard.stripe.com/test/..., así que en un evento del modo de prueba el botón abre una página que no existe. Las disputas de la API de Charges heredada no tienenpayment_intent, lo que deja ese botón con un enlace vacío. - Las suscripciones muestran solo el primer precio.
items.data.0es la primera línea de la factura. El evento incluye un ID de cliente, no un correo. - Cada evento cuenta para tu límite diario. El plan Gratuito tiene 50 mensajes al día. Más allá de eso, Pocket Alert responde
429, y Stripe lo trata como una entrega fallida y, en modo en vivo, reintenta durante hasta tres días.
Nivel 2: un manejador pequeño y verificado
Cuando quieras formato de moneda real, verificación de firmas y un solo endpoint para todos los eventos, pon unas sesenta líneas de Node entre Stripe y Pocket Alert. Usa la biblioteca oficial de Stripe para verificar la firma y POST /v1/messages para enviar la notificación push.
npm install express stripe
// server.mjs
import express from 'express';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();
function money(minor, currency) {
const fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: currency.toUpperCase() });
return fmt.format(minor / 10 ** fmt.resolvedOptions().maximumFractionDigits);
}
function toPush(event) {
const o = event.data.object;
switch (event.type) {
case 'checkout.session.completed':
return { title: `Sale ${money(o.amount_total, o.currency)}`, level: 'default',
message: `${o.customer_details?.email ?? 'no email'} · ${o.payment_status}`,
path: o.payment_intent ? `payments/${o.payment_intent}` : `customers/${o.customer}` };
case 'invoice.payment_failed':
return { title: `Payment failed ${money(o.amount_due, o.currency)}`, level: 'high',
message: `${o.customer_email ?? o.customer} · attempt ${o.attempt_count}`,
path: `invoices/${o.id}` };
case 'charge.dispute.created':
return { title: `Dispute ${money(o.amount, o.currency)}`, level: 'critical',
message: `Reason: ${o.reason}. Evidence due ${new Date(o.evidence_details.due_by * 1000).toDateString()}`,
path: `payments/${o.payment_intent ?? o.charge}` };
case 'customer.subscription.created': {
const price = o.items.data[0]?.price;
return { title: 'New subscription', level: 'low',
message: price?.unit_amount != null
? `${money(price.unit_amount, price.currency)} per ${price.recurring?.interval} · ${o.status}`
: o.status,
path: `subscriptions/${o.id}` };
}
}
return null;
}
app.post('/stripe-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
let event;
try {
event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
} catch (err) {
return res.status(400).send(`Bad signature: ${err.message}`);
}
res.sendStatus(200);
const push = toPush(event);
if (!push) return;
const dashboard = event.livemode ? 'https://dashboard.stripe.com/' : 'https://dashboard.stripe.com/test/';
await fetch('https://api.pocketalert.app/v1/messages', {
method: 'POST',
headers: { Token: process.env.POCKETALERT_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
title: push.title,
message: push.message,
level: push.level,
actions: [{ type: 'view', label: 'Open in Stripe', value: dashboard + push.path }],
}),
}).catch((err) => console.error('Pocket Alert:', err.message));
});
app.listen(process.env.PORT ?? 4242);
STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... POCKETALERT_KEY=... node server.mjs
Los detalles que importan:
express.rawconserva el cuerpo como bytes.constructEventnecesita la petición exactamente como la envió Stripe, y un parser de JSON en el cuerpo rompe la firma. También rechaza eventos de más de cinco minutos, lo que evita reenvíos maliciosos.- El manejador responde
200antes de llamar a Pocket Alert, porque Stripe espera un2xxrápido. Una clave restringida con acceso de lectura basta paraSTRIPE_SECRET_KEY; este código nunca llama a la API de Stripe. Intl.NumberFormatconoce cuántos decimales tiene cada moneda, así que4900 usdse convierte en$49.00y5000 jpyen¥5,000.- El indicador
livemodeelige la ruta correcta del panel, así que los eventos del modo de prueba abren páginas del modo de prueba.
En Stripe, crea un destino de eventos con payload Snapshot, los cuatro eventos y la URL de tu servidor, y luego copia su secreto de firma whsec_ desde la página del destino. Para probar en local, stripe listen --forward-to localhost:4242/stripe-webhook muestra un secreto que puedes usar, y stripe trigger invoice.payment_failed envía un evento de prueba firmado.
El resultado en tu teléfono es una notificación push titulada "Sale $49.00" con "[email protected] · paid" debajo, y una disputa que te despierta con el plazo en el cuerpo.
¿Quieres las ventas y los registros en el mismo flujo? Envía los datos de tu formulario de registro a la misma aplicación y las dos cosas se leerán como un embudo.
Si no llega nada
- Revisa primero Stripe. Abre el destino en Workbench y mira la pestaña Event deliveries. Un
400con "Invalid JSON" significa que llegó a la URL algo que no es JSON de Stripe. Un429significa que alcanzaste el límite diario. - Después, el historial del webhook de Pocket Alert. Si la petición está ahí y el mensaje aparece en blanco en algunas partes, una ruta de la plantilla no existe en ese evento. Copia el cuerpo del historial y comprueba los nombres de los campos.
- Payload thin por error. Si la notificación muestra importes vacíos y el cuerpo del historial tiene
related_objecten lugar dedata, el destino se creó como Thin. Crea uno nuevo con Snapshot. - Errores de firma en el Nivel 2. Cada destino tiene su propio secreto
whsec_, y un secreto de sandbox es distinto del de producción. Asegúrate también de que nada intermedio, como un proxy o un middleware del framework, vuelva a codificar el cuerpo.
Preguntas frecuentes
¿Esto reemplaza la aplicación Stripe Dashboard?
No, y no tiene por qué. La aplicación de Stripe es el lugar para hacer reembolsos, buscar un cliente o revisar tu saldo. Pocket Alert te da la alerta en sí: tu redacción, tus niveles de prioridad y tus botones, en un flujo compartido con el resto de tus alertas de servidores, CI y formularios.
¿Qué eventos merecen una notificación?
Empieza por los cuatro de arriba. invoice.paid es un buen complemento para renovaciones de SaaS, y customer.subscription.deleted te avisa de las cancelaciones. Stripe recomienda suscribirse solo a los eventos que usas, y eso también mantiene tu teléfono en silencio.
¿Puedo recibir una notificación al día en lugar de una por venta?
No desde el webhook. Baja el nivel del webhook de ventas a silent para que las ventas se acumulen en el flujo sin sonido, y reserva high y critical para los eventos que requieren tu atención.
¿Es gratis?
Los webhooks de Stripe no cuestan nada. El plan Gratuito de Pocket Alert cubre 50 mensajes al día en un dispositivo, suficiente para una tienda pequeña. Las alertas críticas que anulan No molestar están en los planes de pago.
Crea una cuenta gratuita, pega una URL en Stripe, y la próxima venta llegará a tu teléfono.