# Cómo gestionar eventos de pago con webhooks

Cómo utilizar webhooks para responder a eventos de pago fuera de línea

Un *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) es un punto de conexión HTTP que recibe eventos desde Stripe.

Los webhooks te permiten recibir notificaciones sobre eventos de pago que suceden fuera de tu flujo de pago, por ejemplo:

- Pagos realizados correctamente (`payment_intent.succeeded`)
- Pagos en disputa (`charge.dispute.created`)
- Saldo disponible en tu cuenta de Stripe (`balance.available`)

Puedes utilizar el Dashboard para acciones puntuales como reembolsar un pago o actualizar la información de un cliente, mientras que los webhooks te ayudan a escalar tu integración de pagos y procesar grandes volúmenes de eventos críticos para la empresa.

## Crea tu propio webhook

Puedes crear un controlador de webhooks en tu propio servidor para gestionar todos los flujos de pagos fuera de línea. Comienza por presentar un punto de conexión que pueda recibir solicitudes de Stripe y que utilice la CLI para probar de manera local tu integración. Cada solicitud de Stripe contiene un objeto [Event](https://docs.stripe.com/api/events/object.md) con una referencia al objeto de Stripe que se modificó.

## Crea un punto de conexión de webhooks

Añade un nuevo punto de conexión en tu aplicación. Puedes actuar sobre determinados eventos corroborando el campo `type` del objeto Event enviado en el cuerpo de la solicitud. Después, podrás usar la salida estándar para asegurarte de que tu webhook funciona.

Inicia tu servidor tras añadir el nuevo punto de conexión.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

require 'stripe'
require 'sinatra'
require 'json'

# Using the Sinatra framework
set :port, 4242

post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

## Instala y configura la CLI de Stripe

Instala la CLI de Stripe con [npm](https://www.npmjs.com/):

```bash
npm install --global @stripe/cli
```

> Para ver más opciones de instalación para Windows, macOS, Linux y Docker, consulta el [readme de la CLI de Stripe](https://github.com/stripe/stripe-cli#installation) en GitHub.

Después de la instalación, conecta la CLI a tu cuenta de Stripe iniciando sesión:

```bash
stripe login
```

La CLI muestra un código de emparejamiento y abre el Dashboard de Stripe, donde apruebas el acceso a las cuentas, los entornos de prueba y el modo activo. La CLI almacena tus credenciales en el almacén de credenciales seguro de tu sistema operativo (cuando está disponible) y actualiza la sesión automáticamente. Para autenticarte con una clave de API en su lugar, ejecuta `stripe login --interactive`, usa `stripe config`, pasa `--api-key` o configura la variable de entorno `STRIPE_API_KEY`.

## Prueba tu webhook de manera local

Utiliza la CLI para reenviar eventos a tu punto de conexión de webhooks local con el comando `listen`.

Si asumimos que tu aplicación está funcionando en un puerto 4242, ejecuta:

```bash
stripe listen --forward-to http://localhost:4242/webhook
```

En otra pestaña del terminal, utiliza el comando `trigger` de la CLI para activar un evento de webhook ficticio.

```bash
stripe trigger payment_intent.succeeded
```

El siguiente evento aparece en tu pestaña `listen`:

```bash
[200 POST] OK payment_intent.succeeded
```

“¡PaymentIntent se completó correctamente!” aparece en la pestaña del terminal que está ejecutando tu servidor.

## Optional: Comprueba la firma del webhook

Stripe incluye una firma en el encabezado `Stripe-Signature` de cada evento. Esto te permite comprobar que fue Stripe quien envió los eventos y no terceros. Puedes verificar las firmas usando nuestras bibliotecas oficiales o [verificar las firmas manualmente](https://docs.stripe.com/webhooks.md#verify-manually) usando tu propia solución.

Primero, busca la clave secreta de tu punto de conexión de webhooks y añádela al controlador de webhooks como `endpoint_secret`. Porque aún estás utilizando la CLI de Stripe para desarrollar tu punto de conexión localmente, utiliza el comando `trigger` para obtener la clave secreta del punto de conexión de webhooks desde la CLI.

```bash
stripe listen
```

La clave secreta del punto de conexión de webhooks comienza con `whsec_` seguido de una serie de números y letras. Guarda esta clave secreta de manera segura y nunca la expongas públicamente.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

## Implementa tu punto de conexión de webhooks

Cuando tengas todo listo para implementar tu punto de conexión de webhook en modo activo, deberás hacer lo siguiente:

1. Utiliza las [claves de API del modo activo](https://docs.stripe.com/keys.md#test-live-modes), no las claves de prueba.
2. Configura tu punto de conexión de webhook en [Workbench](https://docs.stripe.com/workbench.md) o con la API.
3. Para configurar tu punto de conexión en Workbench, ve a la [pestaña Webhooks](https://dashboard.stripe.com/workbench/webhooks).
4. Haz clic en **Añadir destino** e introduce la versión de la API Stripe y los eventos específicos que quieres que Stripe envíe. Haz clic en **Continuar** y selecciona **Punto de conexión de webhook** de la lista de tipos de destino disponibles. Haz clic en **Continuar** e introduce la URL de tu punto de conexión, nombre opcional y descripción opcional. Haz clic en **Crear destino**.
5. Reemplaza la clave secreta del punto de conexión de webhook en tu aplicación por la nueva clave secreta que se muestra en la vista de detalles de destino en Workbench para tu punto de conexión.

Tu aplicación ya está lista para aceptar eventos activos. Para obtener más información sobre cómo configurar tu punto de conexión de webhooks, consulta la API [Webhook Endpoint](https://docs.stripe.com/api/webhook_endpoints.md). Para hacer pruebas en un entorno de prueba, [consulta nuestra guía de desarrollo](https://docs.stripe.com/webhooks.md).