# 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 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
Para obtener más opciones de instalación, consulta [Empezar a usar la CLI de Stripe](https://docs.stripe.com/stripe-cli.md).
Después de que la CLI de Stripe esté instalada, ejecuta `stripe login` en la línea de comandos para generar un código de emparejamiento para vincularla a tu cuenta de Stripe. Presiona **Intro** para iniciar tu navegador e inicia sesión en tu cuenta de Stripe para permitir el acceso. La clave de API que se generó es válida por 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 incluido el indicador [-project-name](https://docs.stripe.com/cli/login#login-project-name) cuando inicies sesión y cuando ejecutes comandos para ese proyecto.

Probar

```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 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 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 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.
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 **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**.
1. 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).