Webhooks de Stripe (cobros fallidos)

Introducción

Cada vez que pasa algo relevante en tu cuenta —se cobra una factura, se rechaza una tarjeta, se da de baja un cliente— Stripe genera un evento: un registro de qué ha pasado, con todos los datos asociados. Y puede enviártelo automáticamente a una dirección web tuya en cuanto ocurre.

Cada tipo de evento tiene un nombre. El de «no se ha podido cobrar» en suscripciones es invoice.payment_failed, y viene acompañado de la factura afectada: qué cliente, cuánto y, a menudo, un enlace para que pague.

En una frase: falla el cobro → Stripe te lo envía → tu sistema reacciona.

Esta guía solo necesita que sepas que existen los avisos automáticos por HTTP. Si eso ya te suena raro, empieza por Introducción a webhooks y vuelve.

Problema que resuelve

Sin webhooks, acabas abriendo el Dashboard de Stripe “por si acaso”. Con un evento, puedes avisar a tu equipo, abrir un ticket o disparar un flujo en el momento del fallo.

Sirve cuando cobras suscripciones o facturas recurrentes y un fallo de tarjeta no puede esperar al final del día.

El evento que importa aquí

Campos útiles dentro de la factura:

Documentación Stripe: tipos de eventos (se abre en una pestaña nueva)↗ · objeto Invoice (se abre en una pestaña nueva)↗.

Anatomía mínima del JSON

Ejemplo recortado (no es un dump completo):

{
  "id": "evt_postnaut_demo_payment_failed",
  "type": "invoice.payment_failed",
  "livemode": false,
  "data": {
    "object": {
      "id": "in_postnaut_demo",
      "customer": "cus_postnaut_demo",
      "customer_email": "demo@postnaut.test",
      "amount_due": 1900,
      "currency": "eur",
      "hosted_invoice_url": "https://invoice.stripe.com/i/acct_demo/test_postnaut"
    }
  }
}

Ese shape es el que mapearás hacia tu destino (email, chat, CRM, cola…).

Ver un evento real (sin destino todavía)

Con el JSON de arriba ya entiendes qué campos mapear. Si además quieres verlo vivo en tu cuenta (opcional):

1. Entra en Stripe y activa Test mode (el interruptor está arriba en el Dashboard).

2. Instala la Stripe CLI (se abre en una pestaña nueva)↗. Es un programa que se maneja escribiendo comandos en la terminal, y sirve para provocar eventos de prueba sin tener que simular un cobro real. Ejecuta stripe login una vez para conectarlo con tu cuenta.

3. En una terminal:

   Lenguaje: bashCopiar código

   stripe trigger invoice.payment_failed

4. Dashboard → Developers → Events: abre el invoice.payment_failed y compara con el ejemplo (type, amount_due, etc.).

Eso demuestra que Stripe emite el evento. Aún no demuestra que tu aviso al equipo funcione: eso es el destino (otro sistema).

Si no quieres instalar la CLI ahora, no pasa nada: el shape del JSON de esta guía es el mismo que verás luego en Events.

Seguridad

Cuando montes el receptor de verdad:

• HTTPS obligatorio en producción.
• El secreto de firma es distinto en test y en live. No lo subas al repositorio.
• Stripe reintenta si no le contestas, así que el mismo cobro fallido puede llegarte varias veces. Guarda el evt_… de los que ya has procesado y descarta los repetidos; si no, mandarás cuatro avisos por el mismo impago.
• Contesta pronto con un 200 y haz después el trabajo lento.

Emisor vs destino

Dos capas distintas:

No intentes firma + CLI + destino el mismo día si es tu primer webhook. Primero entiende el evento; luego el mensaje o la acción; luego el pegamento.

Errores habituales

Siguiente paso

Cuando el evento te quede claro:

1. Una dirección HTTPS tuya que reciba el envío, verifique la firma y se quede solo con los invoice.payment_failed.
2. La acción — avisar al equipo, etiquetar al cliente, encolar un reintento… según tu proceso.
3. Pruébalo entero en modo test antes de tocar el modo live.

Esta guía termina en el evento firmado de Stripe. El destino del aviso (email, chat, CRM, cola…) lo eliges tú según tu proceso.

Automatizaciones guiadas

Aplica lo aprendido en la guía con una de nuestras automatizaciones:

• Stripe → Discord
• Stripe → Telegram