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

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

Crea un destino de evento para recibir eventos en un punto de conexión de webhook HTTPS. Después de que registres un 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 usa HTTPS para enviar eventos de webhook a tu aplicación como una carga JSON que incluye un objeto de evento.

Recibir eventos de webhooks te ayuda a responder a eventos asincrónicos, como cuando el banco de un cliente confirma un pago, un cliente disputa un cargo o un pago recurrente se efectúa correctamente.

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

Empezar

Para comenzar a recibir eventos de webhook en tu aplicación, haz lo siguiente:

1. Crea un controlador de punto de conexión de webhook para recibir solicitudes de POST de datos de eventos.
2. Prueba en forma local tu controlador de puntos de conexión de webhook con la CLI de Stripe.
3. Crea un nuevo destino de evento para el punto de conexión de webhook.
4. Protege el punto de conexión de webhook.

Puedes registrar y crear un punto de conexión para manejar varios tipos de eventos diferentes al mismo tiempo, o configurar puntos de conexión particulares para eventos específicos.

Comportamientos de tipo de evento no admitidos para destinos de eventos de organización

Stripe envía la mayoría de los tipos de eventos de forma asíncrona; sin embargo, para ciertos tipos de eventos, Stripe espera una respuesta. La presencia o ausencia de una respuesta del destino del evento influye directamente en las acciones de Stripe con respecto a estos tipos de eventos específicos.

Los destinos de la organización ofrecen soporte limitado para los tipos de eventos que requieren una respuesta:

• No puedes suscribirte a issuing_authorization.request para destinos de organización. En su lugar, configura un punto de conexión de webhooks en una cuenta de Stripe dentro de la organización para suscribirte a este tipo de evento. Utiliza issuing_authorization.request para autorizar las solicitudes de compra en tiempo real.
• Puedes suscribirte a checkout_sessions.completed para los destinos de la organización. Sin embargo, esto no controla el comportamiento de redireccionamiento cuando integras Checkout directamente en tu sitio web o rediriges a los clientes a una página de pago alojada en Stripe. La entrega de un evento checkout_sessions.completed a un destino de la organización no afectará al comportamiento de redireccionamiento. Para influir en el comportamiento de redireccionamiento de Checkout, procesa este tipo de evento con un punto de conexión de webhook configurado en una cuenta de Stripe dentro de la organización.
• Puedes suscribirte a invoice.created para los destinos de la organización. Sin embargo, si no respondes correctamente a este evento, eso no influirá en la finalización automática de la factura cuando uses el cobro automático. Para influir en la finalización automática de facturas mediante respuestas de punto de conexión de webhook, procesa este tipo de evento con un punto de conexión de webhook configurado en una cuenta de Stripe dentro de la organización.

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

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

  # Extract the context
  context = event.context

  # Define your API key variables (ideally loaded securely)
  ACCOUNT_123_API_KEY = "sk_test_123"
  ACCOUNT_456_API_KEY = "sk_test_456"

  account_api_keys = {
    "account_123" => ACCOUNT_123_API_KEY,
    "account_456" => ACCOUNT_456_API_KEY
  }

  api_key = account_api_keys[context]

  if api_key.nil?
    puts "No API key found for context: #{context}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'customer.created'
    customer = event.data.object

    begin
      latest_customer = Stripe::Customer.retrieve(
        customer.id,
        { api_key: api_key }
      )
      handle_customer_created(latest_customer, context)
    rescue => e
      puts "Error retrieving customer: #{e.message}"
      status 500
      return
    end

  when 'payment_method.attached'
    payment_method = event.data.object

    begin
      latest_payment_method = Stripe::PaymentMethod.retrieve(
        payment_method.id,
        { api_key: api_key }
      )
      handle_payment_method_attached(latest_payment_method, context)
    rescue => e
      puts "Error retrieving payment method: #{e.message}"
      status 500
      return
    end

  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 punto de conexión de webhook, usa la pestaña API o Webhooks en Workbench para registrar la URL accesible de tu punto de conexión de webhook para que Stripe sepa adónde enviar los eventos. Puedes registrar hasta 16 puntos de conexión de webhook en Stripe. Los puntos de conexión de webhook registrados deben ser URL HTTPS de acceso público.

Formato de URL de webhooks

El formato de URL para registrar un punto de conexión de 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 webhooks es @app.route('/stripe_webhooks', methods=['POST']), especifica https://mycompanysite.com/stripe_webhooks como la URL del punto de conexión.

Crea un destino de evento para el punto de conexión de tu webhook

Crea un destino de evento usando Workbench en el Dashboard o mediante programación con la API. Puedes registrar hasta 16 destinos de eventos en cada cuenta de Stripe.

Dashboard

API

Para crear un nuevo punto de conexión de webhook en el Dashboard, haz lo siguiente:

1. Abre la pestaña Webhooks en Workbench.
2. Haz clic en Crea un destino de evento.
3. Selecciona desde dónde quieres recibir los eventos. Stripe admite dos tipos de configuraciones: Tu cuenta y Cuentas conectadas. Selecciona Cuenta para escuchar los eventos de tu propia cuenta. Si has creado una aplicación de Connect y quieres escuchar eventos de tus cuentas conectadas, selecciona Cuentas conectadas.

Escucha los eventos de un punto de conexión de webhooks de la organización

Si creas un punto de conexión de webhook en una cuenta de organización, selecciona Cuentas para escuchar los eventos de las cuentas de tu organización. Si tienes plataformas Connect como miembros de tus organizaciones y quieres escuchar los eventos de las cuentas conectadas de todas las plataformas, selecciona Cuentas conectadas.

1. Selecciona la versión de la API para el objeto Events que quieres consumir.
2. Selecciona los tipos de eventos que quieres enviar a un punto de conexión de webhook.
3. Selecciona Continúa y, a continuación, elige Punto de conexión de webhook como tipo de destino.
4. Haz clic en Continúa y, a continuación, proporciona la URL de punto de conexión y una descripción opcional del webhook.

Registra un nuevo webhook con la pestaña Webhooks

Nota

Workbench sustituye al actual Dashboard de desarrolladores. Si sigues usando el Dashboard de desarrolladores, consulta cómo crear un nuevo punto de conexión webhook.

# 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_BQokikJOvBiI2HlWgH4olfQ2'

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 webhook

Pueden ocurrir varios tipos de problemas al entregar eventos al punto de conexión de tu webhook:

• Es posible que Stripe no pueda entregar un evento a tu punto de conexión de webhook.
• Tu punto de conexión de webhooks podría tener un problema con el SSL.
• La conectividad de tu red es intermitente.
• El punto de conexión de tu webhook no está recibiendo los eventos que esperabas recibir.

Consulta las entregas de eventos

Para ver las entregas de eventos, selecciona el punto de conexión del webhook en Webhooks y, a continuación, selecciona la pestaña Eventos.

The Events tab provides a list of events and whether they’re Delivered, Pending, or Failed. Click an event to view metadata, including the HTTP status code of the delivery attempt and the time of pending future deliveries.

Repara códigos de estado HTTP

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

Comportamientos de entrega de eventos

En esta sección recibirás ayuda para comprender los diferentes comportamientos que puedes esperar en relación con la forma en que Stripe envía los eventos al punto de conexión de tu webhook.

Reintentos automáticos

En modo activo, Stripe intenta entregar eventos en tu destino durante un máximo de tres días con un retroceso exponencial. Consulta cuándo se realizará el siguiente reintento, si corresponde, en la pestaña Entregas de eventos de tu destino de evento. Reintentamos las entregas de eventos creadas en un entorno de prueba tres veces en el transcurso de unas pocas horas. Si tu destino se ha deshabilitado o eliminado cuando hacíamos el reintento, evitamos reintentos de ese evento en el futuro. Sin embargo, si deshabilitas y luego vuelves a habilitar el destino del evento antes de que podamos hacer el reintento, seguirás viendo reintentos en el futuro.

Reintentos manuales

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

Orden de los eventos

Stripe no garantiza la entrega de eventos en el orden en que se han generado. 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)

Asegúrate de que el destino de tu evento no dependa de que recibas los eventos en un orden específico. Prepárate para gestionar la entrega de forma adecuada. También puedes usar la API para recuperar los objetos que falten. Por ejemplo, puedes recuperar los objetos Invoice, Charge y Subscription con la información de invoice.paid si recibes este evento primero.

Control de versiones de API

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an Event sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with versioning, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing Event objects. Retrieving an older Event by calling /v1/events using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The Event sent to the destination is structured for the event destination’s specified version.

Mejores prácticas para el uso de webhooks

Revisa estas prácticas recomendadas para asegurarte de que los puntos de conexión de tu webhook estén protegidos y funcionen bien con tu integración.

Gestiona eventos duplicados

En ocasiones, los puntos de conexión de webhooks pueden recibir el mismo evento más de una vez. Puedes protegerte contra los recibos de eventos duplicados registrando los ID de eventos que has procesado y no procesando los eventos ya registrados.

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

Escucha solo los tipos de eventos que requiere tu integración

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

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

Gestiona 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 decides procesar los eventos de forma sincronizada. Cualquier gran aumento en las entregas de webhook (por ejemplo, a principios de mes, cuando se renuevan todas las suscripciones) podría saturar los servidores de tus puntos de conexión.

Las colas asíncronas te permiten procesar los eventos simultáneos a una velocidad que el sistema puede admitir.

Exime a la ruta de webhook de la protección CSRF

Si usas Rails, Django u otro marco web, tu sitio podría comprobar automáticamente si cada petición POST contiene un token CSRF. Esta es una función de seguridad importante que ayuda a protegerte a ti y a tus usuarios de intentos de falsificación de peticiones 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 excluida 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

Recibir eventos con un servidor HTTPS

Si usas una URL HTTPS para el punto de conexión del webhook (obligatorio en el modo activo), Stripe valida que la conexión con el servidor sea segura antes de enviar los datos de tu webhook. Para que esto funcione, el servidor debe estar correctamente configurado para ser compatible con HTTPS con un certificado de servidor válido. Los webhooks de Stripe solo son compatibles con las versiones v1.2 y v1.3 de TLS.

Cambia periódicamente los secretos de firma de los puntos de conexión

El secreto utilizado para verificar que los eventos provienen de Stripe se puede modificar en la pestaña Webhooks de Workbench. Para mantenerlos a salvo, te recomendamos que renueves (cambies) los secretos periódicamente o cuando sospeches que un secreto se ha visto comprometido.

Cómo cambiar un secreto:

1. Haz clic en cada punto de conexión de la pestaña Webhooks de Workbench para el que quieras renovar el secreto.
2. Dirígete al menú de desbordamiento () y haz clic en Cambiar secreto. Puedes optar por la caducidad inmediatamente del secreto actual o retrasarla por hasta 24 horas para que tengas tiempo de actualizar el código de verificación en tu servidor. Durante este período, habrá varios secretos activos para el punto de conexión. Stripe generará una firma por secreto hasta su caducidad.

Verifica que los eventos se envíen desde Stripe

Stripe envía eventos de webhook desde una lista establecida de direcciones IP. Confía solo en los eventos que provengan de estas direcciones IP.

Verifica también las firmas de webhook para confirmar que Stripe ha enviado los eventos recibidos. Stripe firma los eventos de webhook que envía a tus puntos de conexión incluyendo una firma en el encabezado Stripe-Signature de cada evento. Esto te permite verificar que fue Stripe quien envió los eventos y no un tercero. Puedes verificar las firmas usando nuestras bibliotecas oficiales o verificarlas manualmente usando tu propia solución.

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

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 Workbench y dirígete a la pestaña Webhooks para ver todos tus puntos de conexión. Selecciona un punto de conexión para el que quieras obtener el secreto y, a continuación, haz clic en Haz clic para revelarlo.

Stripe genera una clave secreta única para cada punto de conexión. Si utilizas el mismo punto de conexión para ambas claves de API en modo de prueba y en modo activo, la clave secreta será diferente para cada uno. Además, si utilizas varios puntos de conexión, debes obtener una clave secreta para cada uno de los que quieras verificar las firmas. Después de esta configuración, Stripe comenzará a firmar cada webhook que envía al punto de conexión.

Prevención de ataques de reproducción

Un ataque de repetición ocurre cuando un atacante intercepta una carga válida y su firma, y luego las retransmite. Para mitigar tales ataques, Stripe incluye una marca temporal en el encabezado Stripe-Signature. Debido a que esta marca de tiempo es parte de la carga firmada, también se verifica mediante la firma, por lo que un atacante no puede cambiar la marca temporal sin invalidar la firma. Si la firma es válida, pero la marca temporal es demasiado antigua, tu aplicación puede rechazar la carga.

Nuestras bibliotecas tienen una tolerancia predeterminada de cinco minutos entre la marca temporal y la hora actual. Puedes cambiar esta tolerancia proporcionando un parámetro adicional al verificar las firmas. Utiliza el protocolo de tiempo de redes (NTP) para asegurarte de que el reloj de simulación de tu servidor sea preciso y esté sincronizado con la hora de los servidores de Stripe.

Stripe genera la marca temporal y la firma cada vez que enviamos un evento a tu punto de conexión. Si Stripe reintenta un evento (por ejemplo, tu punto de conexión ha respondido previamente con un código de estado que no es2xx), generaremos una nueva firma y una marca temporal para el nuevo intento de entrega.

Devolver rápidamente una respuesta 2xx

Tu punto de conexión debe devolver rápidamente un código de estado satisfactorio (2xx) antes de que una lógica compleja pueda hacer que se agote el tiempo de espera. Por ejemplo, debes devolver una respuesta 200 antes de actualizar la factura del cliente como pagada en tu sistema contable.