Saltar al contenido principal

Configuración del webhook de Stripe

Si conectaste Stripe usando Connect with Stripe, esta página te guía en el único paso manual que Stripe exige después: crear tú mismo un endpoint de webhook en tu propio panel de Stripe, pantalla por pantalla.

Antes de empezar​

  • Esto solo se aplica a Connect with Stripe. Si conectaste Stripe introduciendo tú mismo tu Clave secreta y Clave pública (ver Pagos — Conectar Stripe), Agon registra el webhook automáticamente y no necesitas esta página.
  • Por qué tienes que hacerlo tú mismo: Stripe no permite que una cuenta conectada por OAuth ("Connect") registre endpoints de webhook automáticamente — es una restricción del lado de Stripe, no una limitación de Agon. Solo necesitas hacerlo una vez.
  • Ten a mano la URL de webhook de tu estudio. Se muestra en Agon bajo Configuración → Facturación, y tiene este aspecto: https://studio-<id-de-tu-estudio>.agon-studio.dev/api/billing/webhook — única para tu estudio. Deja esa página abierta en otra ventana o pestaña para poder copiarla en el paso 7.

Pasos​

  1. Abre tu panel de Stripe y ve a Developers → Webhooks — o directamente a Workbench → Webhooks.

  2. Haz clic en Add destination.

    Página de Webhooks del Workbench de Stripe con el botón Add destination

  3. Stripe abre un asistente Create an event destination de tres pasos: Select events → Choose destination type → Configure your destination.

  4. En Select events, bajo Event destination scope, elige Your account — no Connected accounts, que es solo para plataformas que escuchan eventos de las cuentas de Stripe de otras personas. Tu estudio es esa cuenta. Bajo Payload style, deja seleccionado Snapshot — no Thin; Agon necesita el objeto de evento completo, no solo un id que habría que consultar después. Deja API version en el valor que Stripe proponga por defecto.

    Configure your event destination: Your account y Snapshot seleccionados

  5. Todavía en Select events, usa el cuadro de búsqueda Find event by name or description… — mucho más rápido que examinar todo el árbol de categorías — y marca exactamente estos 6 eventos, uno a uno:

    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.paid
    • invoice.payment_failed

    Cuadro de búsqueda de eventos: Find event by name or description

    Una vez marcados los 6, haz clic en Continue.

  6. En Choose destination type, selecciona Webhook endpoint — la primera opción. Las otras dos, Amazon EventBridge y Azure Event Grid, sirven para enviar eventos a tu propia infraestructura en la nube y no aplican aquí. Haz clic en Continue.

    Choose destination type con Webhook endpoint seleccionado

  7. En Configure your destination, Stripe muestra un resumen de tus elecciones (Events from: Your account, Payload style: Snapshot, Listening to: 6 events), seguido de tres campos:

    • Destination name — opcional, cualquier nombre sirve (por ejemplo "Agon"). Solo es una referencia para ti en tu panel de Stripe y no tiene ningún efecto funcional.
    • Endpoint URL — pega aquí la URL de webhook de tu estudio desde la página Configuración → Facturación de Agon, exactamente como se muestra. No la escribas a mano — un solo error tipográfico hace que Stripe nunca pueda llegar a tu estudio.
    • Description — opcional, puede dejarse vacío.

    Haz clic en el botón para crear el destino.

    Configure destination con los campos Destination name, Endpoint URL y Description

  8. Stripe muestra ahora un Signing secret para tu nuevo destino, a veces detrás de un control "reveal" que hay que pulsar antes. Cópialo.

  9. En Agon, ve a Configuración → Facturación y pégalo en el campo Secreto del webhook — el mismo campo descrito en Pagos — Conectar Stripe, siempre visible en esa página y no oculto tras una opción adicional. Haz clic en Guardar.

¿Y si algo sale mal?​

No estoy seguro de si elegir "Your account" o "Connected accounts"

Elige Your account. Tu estudio es la cuenta de Stripe que estás configurando — Connected accounts solo aplica si fueras una plataforma que recibe eventos de las cuentas de Stripe separadas de otras personas, lo que no es el caso aquí.

Mis pagos siguen mostrándose como Pendientes después de configurar esto

Comprueba que la Endpoint URL se pegó exactamente, sin caracteres de más ni segmentos faltantes, y que el Secreto del webhook guardado en Configuración → Facturación coincide con el signing secret que Stripe muestra para ese destino concreto. Ver también Pagos — ¿Y si algo sale mal?.

Necesito añadir un evento más adelante o cambiar la URL

Vuelve a abrir el destino desde Workbench → Webhooks en tu panel de Stripe y edítalo allí. Solo necesitas actualizar algo en Agon si también cambia el signing secret.

Páginas relacionadas​