# 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 efectuados con éxito (`payment_intent.succeeded`)
- Pagos en disputa (`charge.dispute.created`)
- Saldo disponible en tu cuenta de Stripe (`balance.available`)

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

## Crear tu propio webhook

Puedes crear un controlador de webhooks en tu propio servidor para administrar 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

Agrega un nuevo punto de conexión en tu aplicación. Puedes actuar sobre determinados eventos marcando el campo `type` del objeto Event enviado en el cuerpo de la solicitud. Luego, puedes imprimir la salida estándar para asegurarte de que el webhook esté funcionando.

Inicia tu servidor luego de agregar 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 obtener más información sobre las opciones de instalación para Windows, macOS, Linux y Docker, consulta el archivo [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 e inicia sesión.

```bash
stripe login
```

La CLI muestra un código de vinculación y abre el Dashboard de Stripe, en el que apruebas el acceso a las cuentas, los entornos de prueba y el modo activo. La CLI almacena tus credenciales en el almacén seguro de credenciales de tu sistema operativo (cuando está disponible) y actualiza la sesión automáticamente. Para autenticar con una clave de API en su lugar, ejecuta `stripe login --interactive`, usa `stripe config`, pasa `--api-key` o establece 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 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 simulado.

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

En la pestaña `listen`, aparece el siguiente evento:

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

«¡El PaymentIntent se completó con éxito!» aparece en la pestaña del terminal que está ejecutando tu servidor.

## Optional: Corroborar la firma del webhook

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

Primero, busca la clave secreta de tu punto de conexión de webhooks y agrégala al controlador de webhooks como `endpoint_secret`. Como estás utilizando la CLI de Stripe para desarrollar nuestro 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 esté todo listo para implementar tu punto de conexión de webhook en modo activo, debes hacer lo siguiente:

1. Usa tus [claves de API en modo activo](https://docs.stripe.com/keys.md#test-live-modes) y no tus 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 **Agregar destino** e ingresa la versión de la API de Stripe y los eventos específicos que deseas 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 ingresa la URL de tu punto de conexión, un nombre opcional y una descripción opcional. Haz clic en **Crear destino**.
5. Reemplaza el secreto del punto de conexión de webhook en tu aplicación con el nuevo secreto que se muestra en la vista de detalles del destino en Workbench para tu punto de conexión.

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