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

> Apunta un webhook de Stripe a Pocket Alert y recibe una notificación push por cada pago, factura fallida, disputa y suscripción nueva. Sin código para lo básico, unas sesenta líneas de Node para importes con formato y firmas verificadas.

*20.10.2026*

<!-- source: https://pocketalert.app/es/blog/stripe-payment-notifications -->

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](/use-cases/payment-alerts) 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](/account/apikeys) y la aplicación en tu [iPhone o Android](/get-app).
- 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](/tools/webhook) 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](/pricing) de pago, que además desbloquea los botones.

Puedes crear webhooks en la consola, en [Webhooks](/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:

```bash
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:

```json
{
  "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%\"}]"
}
```

```json
{
  "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%\"}]"
}
```

```json
{
  "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:

1. Elige **Your account**.
2. 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.
3. Selecciona el evento, por ejemplo `checkout.session.completed`.
4. 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:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Evento de Stripe</th><th>Webhook de Pocket Alert</th><th>Título de la notificación</th><th>Nivel</th></tr></thead>
<tbody>
<tr><th><code>checkout.session.completed</code></th><td>Stripe sale</td><td>Webhook Stripe sale</td><td>default</td></tr>
<tr><th><code>invoice.payment_failed</code></th><td>Stripe payment failed</td><td>Webhook Stripe payment failed</td><td>high</td></tr>
<tr><th><code>charge.dispute.created</code></th><td>Stripe dispute</td><td>Webhook Stripe dispute</td><td>critical</td></tr>
<tr><th><code>customer.subscription.created</code></th><td>Stripe subscription</td><td>Webhook Stripe subscription</td><td>low</td></tr>
</tbody>
</table>
</div>

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í:

```text
Webhook Stripe sale
4900 usd from alex@example.com (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 `4900` para 49,00 $ y `5000` para ¥5000, porque el yen no tiene céntimos. La plantilla copia los valores tal cual y no puede dividir entre 100. Aprenderás a leer `4900 usd` rá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 tienen `payment_intent`, lo que deja ese botón con un enlace vacío.
- **Las suscripciones muestran solo el primer precio.** `items.data.0` es 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.

```bash
npm install express stripe
```

```js
// 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);
```

```bash
STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... POCKETALERT_KEY=... node server.mjs
```

Los detalles que importan:

- `express.raw` conserva el cuerpo como bytes. `constructEvent` necesita 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 `200` antes de llamar a Pocket Alert, porque Stripe espera un `2xx` rápido. Una clave restringida con acceso de lectura basta para `STRIPE_SECRET_KEY`; este código nunca llama a la API de Stripe.
- `Intl.NumberFormat` conoce cuántos decimales tiene cada moneda, así que `4900 usd` se convierte en `$49.00` y `5000 jpy` en `¥5,000`.
- El indicador `livemode` elige 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 "alex@example.com · 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](/use-cases/signup-alerts) 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 `400` con "Invalid JSON" significa que llegó a la URL algo que no es JSON de Stripe. Un `429` significa 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_object` en lugar de `data`, 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](/pricing) de pago.

[Crea una cuenta gratuita](/signup), pega una URL en Stripe, y la próxima venta llegará a tu teléfono.
