Recibe eventos de Stripe en tu punto de conexión de webhook

Al crear integraciones de Stripe, es posible que desees que tus aplicaciones reciban eventos a medida que ocurren en tus cuentas de Stripe, para que tus sistemas de back-end puedan ejecutar las acciones que sean necesarias.

Crea un destino de evento para recibir eventos en un punto de conexión de webhook HTTPS. Después de registrar el punto de conexión de webhook, Stripe puede enviar datos de eventos en tiempo real al punto de conexión de webhook de tu aplicación cuando se produzcan eventos en tu cuenta de Stripe. Stripe utiliza HTTPS para enviar eventos de webhook a tu aplicación como una carga JSON que incluye un objeto Event.

Recibir eventos de webhook es particularmente útil para escuchar eventos asincrónicos, por ejemplo, cuando el banco del cliente confirma un pago, un cliente disputa un cargo, se efectúa correctamente un pago recurrente o se cobran pagos de suscripciones.

También puedes recibir eventos en Amazon EventBridge con destinos de eventos.

Empezar

Para comenzar a recibir eventos de webhook en tu aplicación, crea y registra un punto de conexión de webhook:

1. Crea un controlador de punto de conexión de webhook para recibir solicitudes POST de datos de eventos.
2. Prueba el controlador del punto de conexión de tu webhook a nivel local con la CLI de Stripe.
3. Registra tu punto de conexión dentro de Stripe usando el Dashboard o la API.
4. Asegura tu punto de conexión de webhook.

Puedes registrarte y crear un punto de conexión para manejar varios tipos de eventos diferentes a la vez, o bien configurar puntos de conexión individuales para eventos específicos.

require 'json'

# Using Sinatra
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
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

Registra tu punto de conexión

Después de probar la función de tu punto de conexión de webhook, registra la URL accesible del punto de conexión de webhook con la sección Webhooks en el Dashboard para desarrolladores o la API, para que Stripe sepa dónde enviar los eventos. Puedes registrar hasta 16 puntos de conexión de webhook con Stripe. Los puntos de conexión de webhook registrados deben ser URL HTTPS de acceso público.

Formato de URL del webhook

El formato de la URL para registrar un punto de conexión del webhook es el siguiente:

https://<your-website>/<your-webhook-endpoint>

Por ejemplo, si tu dominio es https://mycompanysite.com y la ruta a tu punto de conexión de webhook es @app.route('/stripe_webhooks', methods=['POST']), especifica https://mycompanysite.com/stripe_webhooks como la URL del punto de conexión.

Crear un nuevo punto de conexión de webhook

You can create new event destinations for webhook and AWS EventBridge destinations.

1. Open the Event destinations tab in Workbench.
2. Click Create new destination.
3. Selecciona la versión de API para el objeto Events que quieres consumir.
4. Si estás utilizando Connect, puedes escuchar Eventos en las cuentas conectadas. De lo contrario, elige Eventos en tu cuenta.
5. Select the event types that you want to send to the destination, then click Continue.
6. Select Webhook to send events to an HTTPS endpoint.
7. Proporciona la URL del punto de conexión a la que deseas que Stripe envíe los webhooks y una descripción opcional para el punto de conexión.
8. Haz clic en Crear destino para crear un punto de conexión de webhooks.

Nota

Workbench reemplaza el Dashboard para desarrolladores existente. Si todavía estás usando el Dashboard para desarrolladores, consulta cómo crear un nuevo punto de conexión de webhooks.

Registra un punto de conexión de webhook con la API de Stripe

También puedes crear puntos de conexión de webhooks mediante programación.

Para recibir eventos de cuentas conectadas, usa el parámetro connect.

En el siguiente ejemplo, se crea un punto de conexión que te notifica si los cargos se concretan o no.

Command Line

curl

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "url"="https://example.com/my/webhook/endpoint" \
  -d "enabled_events[]"="payment_intent.payment_failed" \
  -d "enabled_events[]"="payment_intent.succeeded"

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

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

Depura las integraciones de webhooks

Pueden ocurrir varios tipos de problemas al entregar eventos a tu punto de conexión de webhooks, por ejemplo:

• Es posible que Stripe no pueda entregar un evento al punto de conexión de tu webhook.
• Es posible que el punto de conexión de tu webhook tenga un problema de SSL.
• Tu conectividad de red es intermitente.
• El punto de conexión de tu webhook no está recibiendo los eventos que esperas recibir.

Visualiza las entregas de eventos

Para ver las entregas de eventos para un punto de conexión específico, selecciona el punto de conexión del webhook en la pestaña Webhooks.

Para ver todos los eventos que se activaron en tu cuenta, consulta la pestaña Eventos.

Corrige los códigos de estado HTTP

Cuando un evento muestra un código de estado 200, indica una entrega correcta al punto de conexión de webhook. También puedes recibir un código de estado que no sea 200. En la siguiente tabla, encontrarás una lista de códigos de estado HTTP comunes y soluciones recomendadas.

Comportamientos de entrega de eventos

En esta sección, se brinda ayuda para comprender los diferentes comportamientos que puedes esperar en cuanto a la forma en que Stripe envía eventos a tu punto de conexión de webhook.

Comportamiento de reintentos

En modo activo, Stripe intenta entregar un evento determinado al punto de conexión del webhook durante un lapso máximo de tres días con un retroceso exponencial. En la sección Eventos del Dashboard, puedes consultar cuándo se hará el siguiente reintento.

En modo de prueba, Stripe hace tres reintentos en el curso de algunas horas. Una vez transcurrido este tiempo, puedes reintentar manualmente la transmisión de eventos individuales al punto de conexión de tu webhook utilizando la sección Eventos del Dashboard. También puedes consultar los eventos faltantes para conciliar los datos en algún período.

Los reintentos automáticos continúan, incluso si vuelves a intentar la transmisión manual de eventos de webhook individuales a un punto de conexión determinado y el intento se realiza correctamente.

Si tu punto de conexión se deshabilitó o se eliminó durante un reintento de Stripe, se evitarán futuros reintentos de ese evento. No obstante, si deshabilitas y luego vuelves a habilitar un punto de conexión de webhook antes de que Stripe haga un reintento, aún es posible que haya reintentos en el futuro.

Deshabilita el comportamiento

En modo activo y de prueba, Stripe intenta enviarte un correo electrónico para notificarte que un punto de conexión está mal configurado si el punto de conexión no respondió con el código de estado HTTP 2xx durante varios días seguidos. En el correo electrónico también se te indicará cuándo se deshabilitará automáticamente el punto de conexión.

Control de versiones de la API

La versión de la API en la configuración de tu cuenta cuando ocurre el evento dicta la versión de la API y, por lo tanto, la estructura de un objeto Event enviado en un webhook. Por ejemplo, si tu cuenta está configurada en una versión de API anterior, como 2015-02-16, y cambias la versión de la API para una solicitud específica con control de versiones, el objeto Event generado y enviado a tu punto de conexión se seguirá basando en la versión de API 2015-02-16.

No puedes cambiar los objetos Event después de crearlos. Por ejemplo, si actualizas un cargo, el evento original del cargo no variará, lo que significa que las actualizaciones posteriores de la versión de la API de tu cuenta no alteran los objetos Event existentes de forma retroactiva. La recuperación de eventos anteriores llamando a /v1/events con una versión más nueva de la API tampoco influye en la estructura de los eventos recibidos.

Puedes definir puntos de conexión de webhook de prueba para tu versión de API predeterminada o para la última versión de API. El Event enviado a la URL del webhook se estructura para la versión del punto de conexión que se haya especificado. También puedes crear puntos de conexión mediante programación con una api_version específica.

Pedido de eventos

Stripe no garantiza la entrega de eventos en el orden en que se generaron. Por ejemplo, la creación de una suscripción puede generar los siguientes eventos:

• customer.subscription.created
• invoice.created
• invoice.paid
• charge.created (si hay un cargo)

Tu punto de conexión no debe esperar que los eventos lleguen en este orden y debe manejar la entrega en consecuencia. También puedes usar la API para recuperar los objetos faltantes (por ejemplo, puedes recuperar los objetos de factura, cargo y suscripción con la información de invoice.paid si recibes este evento primero).

Prácticas recomendadas para usar webhooks

Revisa estas prácticas recomendadas para asegurarte de que tus webhooks estén protegidos y funcionen correctamente con tu integración.

Maneja los eventos duplicados

Los puntos de conexión de webhooks ocasionalmente pueden recibir el mismo evento más de una vez. Para protegerte contra los recibos de eventos duplicados, puedes registrar los ID de evento que procesaste y luego no procesar los eventos ya registrados.

En algunos casos, se generan y envían dos objetos Event separados. Para identificar estos duplicados, utiliza la ID del objeto en data.object junto con el event.type.

Escucha únicamente los tipos de eventos que tu integración requiere

Configura tus puntos de conexión de webhook para recibir solo los tipos de evento que necesita tu integración. Si escuchas otros eventos (o todos los eventos), se producirá una saturación indebida en tu servidor que no recomendamos.

Puedes modificar los eventos que recibe un punto de conexión de webhook en el Dashboard o con la API.

Administra eventos de forma asíncrona

Configura tu controlador para procesar eventos entrantes con una cola asíncrona. Es posible que tengas problemas de escalabilidad si eliges procesar los eventos de forma sincrónica. Todos los picos que se puedan producir en las entregas de webhook (por ejemplo, a principios de mes, cuando se renuevan todas las suscripciones) podrían saturar los hosts de los puntos de conexión.

Las colas asincrónicas te permiten procesar los eventos simultáneos a una velocidad que tu sistema puede soportar.

Ruta de webhook exenta de la protección CSRF

Si usas Rails, Django u otro framework web, tu sitio podría comprobar automáticamente si cada solicitud POST contiene un token CSRF. Esta es una funcionalidad de seguridad importante que ayuda a protegerte a ti y a tus usuarios contra intentos de falsificación de solicitudes en sitios cruzados. No obstante, esta medida de seguridad también puede impedir que tu sitio procese eventos legítimos. De ser así, quizá sea necesario que la ruta de webhooks quede exenta de la protección CSRF.

class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end

Recibe eventos con un servidor HTTPS

Si usas una URL HTTPS para tu punto de conexión de webhooks (obligatorio en modo activo), Stripe validará que la conexión con tu servidor sea segura antes de enviar tus datos de webhook. Para que esto funcione, tu servidor debe estar configurado correctamente de manera de admitir HTTPS con un certificado de servidor válido. Los webhooks de Stripe solo admiten versiones v1.2 y v1.3 de TLS.

Cambia los secretos de firma del punto de conexión periódicamente

El secreto utilizado para verificar que los eventos provengan de Stripe se puede modificar en la sección Webhooks del Dashboard. Para cada punto de conexión, haz clic en Cambiar secreto. Puedes optar por que el secreto actual venza de inmediato o que postergue su vencimiento hasta 24 horas para tener tiempo de actualizar el código de verificación en tu servidor. Durante este lapso, habrá varios secretos activos para el punto de conexión. Stripe genera una firma por secreto hasta su vencimiento. Como medida de protección, te recomendamos que cambies los secretos periódicamente o cuando sospeches que alguno de ellos está comprometido.

Verifica que los eventos provengan de Stripe

Stripe envía eventos de webhook desde una lista prestablecida de direcciones IP. Confía solo en los eventos provenientes de estas direcciones IP.

Además, verifica las firmas del webhook para confirmar que los eventos recibidos se envían desde Stripe. Stripe firma los eventos de webhook que envía a tus puntos de conexión, incluida una firma en el encabezado Stripe-Signature de cada evento. Esta acción te permite corroborar que los eventos fueron enviados por Stripe y no por un tercero. Puedes verificar las firmas con nuestras bibliotecas oficiales o hacerlo de forma manual con tu propia solución.

En la siguiente sección se describe cómo verificar las firmas de webhooks:

1. Recupera el secreto de tu punto de conexión.
2. Verifica la firma.

Cómo recuperar el secreto de tu punto de conexión

Usa la sección Webhooks del Dashboard. Selecciona el punto de conexión cuyo secreto desees obtener; el secreto se encuentra en la parte superior derecha de la página.

Stripe genera un secreto único para cada punto de conexión. Si usas el mismo punto de conexión para las claves de API de prueba y activas, el secreto será diferente para cada una. Además, si usas varios puntos de conexión, deberás obtener un secreto para cada uno en el que quieras verificar las firmas, y Stripe comenzará a firmar cada webhook que envía al punto de conexión.

Cómo prevenir ataques de reproducción

Un ataque de reproducción se produce cuando un atacante intercepta una carga válida y su firma, y luego la vuelve a transmitir. Para mitigar estos ataques, Stripe incluye una marca de tiempo en el encabezado Stripe-Signature. Dado que esta marca de tiempo forma parte de la carga firmada, también se verifica mediante la firma, por lo que un atacante no puede cambiar la marca de tiempo sin invalidar la firma. Si la firma es válida, pero la marca de tiempo es demasiado antigua, puedes hacer que tu aplicación rechace la carga.

De manera predeterminada, nuestras bibliotecas tienen una tolerancia de 5 minutos entre la marca de tiempo y la hora actual. Proporciona un parámetro adicional al verificar las firmas para modificar esta tolerancia. Usa el protocolo de tiempo de redes (NTP) para garantizar que el clock de tu servidor sea preciso y esté sincronizado con la hora de los servidores de Stripe.

Stripe genera la marca de tiempo y la firma cada vez que enviamos un evento a tu punto de conexión. Si Stripe reintenta un evento (por ejemplo, porque el punto de conexión envió un código de estado que no es 2xx), se generan una firma y una marca de tiempo nuevas para el nuevo intento de entrega.

Devuelve rápidamente una respuesta 2xx

Tu punto de conexión debe devolver de inmediato un código de estado correcto (2xx) antes de que alguna lógica compleja pueda provocar un error de tiempo de espera agotado. Por ejemplo, debes devolver una respuesta 200 antes de registrar la factura del cliente como pagada en tu sistema contable.