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

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 debidamente.

Create an event destination to receive events at an HTTPS webhook endpoint. After you register a webhook endpoint, Stripe can push real-time event data to your application’s webhook endpoint when events happen in your Stripe account. Stripe uses HTTPS to send webhook events to your app as a JSON payload that includes an Event object.

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

You can also receive events in Amazon EventBridge with event destinations.

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 webhooks para recibir peticiones de POST de datos de eventos.
2. Prueba el controlador del punto de conexión de tu webhook a nivel local utilizando la CLI de Stripe.
3. Registra tu punto de conexión dentro de Stripe utilizando el Dashboard o la API.
4. Protege el punto de conexión de tu 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.

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 punto de conexión de webhook, registra la URL accesible del punto de conexión de webhook utilizando la Sección de 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 de webhooks

El formato de URL para registrar un punto de conexión de webhooks 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 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. Select the API version for the events object you want to consume.
4. If you’re using Connect, you can listen for Events on connected accounts. Otherwise, choose Events on your account.
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. Provide the Endpoint URL for Stripe to send webhooks to and an optional description for the endpoint.
8. Click Create destination to create your webhook endpoint.

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.

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

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

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

En el siguiente ejemplo, se crea un punto de conexión que te notifica cuando los cargos se realizan correctamente o fallan.

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 integraciones de webhooks

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

• Es posible que Stripe no pueda enviar 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.
• 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 consultar las entregas de eventos para un punto de conexión específico, elige el punto de conexión de webhooks en la pestaña Webhooks.

Para consultar todos los eventos que se han activado en tu cuenta, consulta la pestaña Eventos.

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.

Reintenta el comportamiento

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

En el modo de prueba, Stripe vuelve a intentarlo tres veces en unas pocas horas. Puedes volver a intentar manualmente transmitir eventos particulares a tu punto de conexión de webhook después de este tiempo utilizando la sección Eventos del Dashboard. También puedes consultar los eventos omitidos para conciliar los datos durante cualquier período.

Los reintentos automáticos se mantienen, incluso si vuelves a intentar transmitir manualmente eventos de webhook particulares a un punto de conexión determinado y el intento se realiza correctamente.

Si se ha deshabilitado o eliminado tu punto de conexión al hacer el reintento con Stripe, se evitarán futuros reintentos de ese evento. No obstante, si deshabilitas y luego vuelves a habilitar un punto de conexión de webhooks antes de que Stripe pueda reintentarlo, es posible que sigas viendo reintentos en el futuro.

Deshabilitar comportamiento

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

Control de versiones de API

La versión de la API en la configuración de tu cuenta cuando se produce 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 API para una petición específica con el control de versiones, el objeto Event generado y enviado a tu punto de conexión todavía estará establecido en la versión de API 2015-02-16.

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

Puedes definir puntos de conexión de webhooks 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.

Orden de los eventos

Stripe no garantiza la entrega de eventos en el orden en que generan. 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 gestionar el proceso según corresponda. También puedes usar la API para recuperar los objetos que falten (por ejemplo, puedes recuperar los objetos de invoice, cargo y suscripción usando la información de invoice.paid si recibes este evento primero).

Mejores prácticas para usar webhooks

Revisa estas mejores prácticas para asegurarte de que tus webhooks estén protegidos y funcionen correctamente 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.

Gestionar 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 tu sistema puede soportar.

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

Recibe 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 provengan de Stripe se puede modificar en la sección Webhooks del Dashboard. Para cada punto de conexión, haga clic en Cambiar secreto. Puedes optar por la caducidad inmediata 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 la caducidad. Para mantenerlos a salvo, te recomendamos que cambies los secretos periódicamente, o cuando sospeches que un secreto se ha visto comprometido.

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.

Asimismo, verifica las firmas del webhook para confirmar que los eventos recibidos se envíen desde Stripe. 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. Esta medida te permite verificar que Stripe ha enviado los eventos en lugar de terceros. 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 la sección Webhooks del Dashboard. Elige un punto de conexión del que quieras obtener el secreto y busca el secreto en la parte superior derecha de la página.

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

Prevención de ataques de repetició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 5 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 clock 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.

Devuelve 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.