# Handle payment events with webhooks

How to use webhooks to respond to offline payment events.

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
Para obtener más opciones de instalación, consulta [Empezar con la CLI de Stripe](https://docs.stripe.com/stripe-cli.md).
Después de que hayas instalado la CLI de Stripe, ejecuta `stripe login` en la línea de comandos para generar un código de emparejamiento para vincularla a tu cuenta de Stripe. Pulsa **Intro** para iniciar tu navegador e inicia sesión en tu cuenta de Stripe para permitir el acceso. La clave de API que se genera es válida durante 90 días. Puedes modificarla o eliminarla desde [Claves de API](https://dashboard.stripe.com/apikeys) en el Dashboard.

> Puedes crear una configuración específica del proyecto incluyendo la bandera [-project-name](https://docs.stripe.com/cli/login#login-project-name) cuando inicies sesión y cuando ejecutes comandos para ese proyecto.

Prueba

```bash
stripe login
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

Si quieres utilizar una clave de API existente, utiliza la marca `--api-key`:

```bash
stripe login --api-key <<YOUR_SECRET_KEY>>
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

## 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 Dashboardendpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

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

  beginevent = 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.
1. Configura tu punto de conexión de webhook en [Workbench](https://docs.stripe.com/workbench.md) o con la API.
1. Para configurar tu punto de conexión en Workbench, ve a la [pestaña Webhooks](https://dashboard.stripe.com/workbench/webhooks).
1. 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**.
1. 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).