Recibe eventos de Stripe en tu punto de conexión de webhook
Envía eventos a tu cuenta de AWS
Estamos admitiendo la recepción de eventos de Stripe en Amazon EventBridge en la versión beta privada. Para obtener acceso anticipado, crea una cuenta en eventbridge.stripe.dev.
Por qué usar webhooks
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.
Para habilitar los eventos de webhook, debes registrar los puntos de conexión de webhook. Después de registrarlos, 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.
Resumen del evento
Stripe genera datos de eventos que podemos enviarte para informar sobre la actividad en tu cuenta.
Cuando se produce un evento, Stripe genera un nuevo objeto Event. Una sola solicitud de API puede dar lugar a la creación de varios eventos. Por ejemplo, si creas una nueva suscripción para un cliente, recibirás los eventos customer.subscription.created
y payment_intent.succeeded
.
Registra puntos de conexión de webhook en tu cuenta de Stripe para habilitar a Stripe a que envíe automáticamente objetos Event como parte de las solicitudes POST al punto de conexión de webhook registrado que aloja tu aplicación. Después de que tu punto de conexión de webhook reciba el Event, tu aplicación puede ejecutar acciones de back-end (por ejemplo, llamar a las API de tu proveedor de envíos para programar un envío después de recibir un evento payment_intent.succeeded
).
Objeto Event
El objeto Event que enviamos a tu punto de conexión de webhook proporciona una instantánea del objeto que cambió. En ellos, es posible que se incluya una propiedad previous_attributes
que indique el cambio, cuando corresponda.
Consulta la lista completa de tipos de eventos que enviamos a tu webhook.
Ejemplo de carga de evento
El siguiente evento muestra una actualización de la suscripción al final de una prueba.
{ "id": "evt_1MqqbKLt4dXK03v5qaIbiNCC", "object": "event", "api_version": "2024-04-10", "created": 1680064028,
Estructura del objeto Event
Revisa la estructura del objeto Event para comprender mejor los eventos y la información subyacente que proporcionan.
Tipo de evento
Recibes eventos para todos los tipos de eventos que tu punto de conexión de webhook esté escuchando en tu configuración. Utiliza el evento type
recibido para determinar qué procesamiento debe ejecutar tu aplicación. El data.object
correspondiente a cada evento type
varía.
Modo activo y de prueba
Es posible que recibas solicitudes de entrega de eventos en modo activo y en modo de prueba en tus puntos de conexión. Estas acciones pueden suceder si utilizas un único punto de conexión tanto para el modo activo como para el modo de prueba, o si utilizas una plataforma Connect que realiza solicitudes de modo de prueba para cuentas conectadas Standard activas. Utiliza el atributo livemode
para verificar si el objeto existe en modo activo o de prueba a fin de determinar la manera correcta de manejar el evento.
Versión de API
La api_version
indica la versión de API del evento y dicta la estructura del data.object incluido. Tu punto de conexión recibe eventos utilizando la versión de API configurada, que puede diferir de la versión de API predeterminada de tu cuenta o de la versión de API de alguna solicitud relacionada con el evento. Este atributo está determinado por el punto de conexión de destino, lo que indica que el mismo evento podría entregarse a varios puntos de conexión utilizando diferentes versiones de API. Si utilizas nuestras bibliotecas de cliente Java, .NET o Go, asegúrate de configurar la versión de API del punto de conexión para que utilice la misma versión de API anclada en el cliente. De lo contrario, es posible que no puedas revertir la serialización de los objetos de evento.
Al recuperar los objetos Event de la API, no puedes controlar la versión de la API de la estructura data.object
. En su lugar, recupera ese objeto desde el punto de conexión de la API correspondiente y usa el encabezado Stripe-Version
para especificar una versión de la API.
Eventos de solicitud de API
Cuando se genera un evento como resultado de una solicitud de API, esa solicitud aparece como request.id
. Si usas una idempotency_key
al hacer la solicitud, se incluirá como request.idempotency_key
. Marca este hash request
cuando investigues qué causa un evento.
Objeto Data y atributos anteriores
Para los eventos *.updated
, la carga del evento incluye data.previous_attributes
que te permiten inspeccionar qué cambió en el objeto Stripe. El evento previous_ attributes
en el ejemplo customer.subscription.updated
anterior indica que la suscripción tiene un valor anterior de status: trialing
, entre otros cambios. El data.object
indica que el estado es active
, lo que implica que la suscripción salió de un período de prueba.
Entregas pendientes
Usa pending_webhooks
para determinar cuántos puntos de conexión configurados para este evento no respondieron correctamente a la entrega. Durante la entrega inicial, este valor es de 1 o superior porque tu punto de conexión no respondió correctamente. Si recuperas este evento más tarde, los pending_webhooks
disminuyen a un mínimo de 0 a medida que cada punto de conexión responde correctamente. Este punto es importante para los eventos invoice.created
, ya que las entregas fallidas pueden retrasar la finalización de la factura.
Eventos de cuentas conectadas
Los eventos de cuentas conectadas entregados a un punto de conexión de Connect incluyen la account
. Usa account
para rastrear a qué cuenta conectada pertenece el objeto a fin de asegurarte de que tu plataforma pueda procesar los datos del evento de manera adecuada.
Por qué se generan objetos de evento
En esta tabla se describen diferentes escenarios que generan objetos Event.
Origen | Activación |
---|---|
Dashboard | Cuando llamas a una API modificando tus recursos de Stripe en el Dashboard de Stripe. |
API | Cuando la acción de un usuario en tu aplicación o sitio web da como resultado una llamada API. |
API | Cuando se activa manualmente un evento con la CLI de Stripe. |
API | Cuando llamas a una API directamente con la CLI de Stripe. |
Empezar
Para comenzar a recibir eventos de webhook en tu aplicación, crea y registra un punto de conexión de webhook. Para hacerlo, sigue los pasos a continuación:
- Crea un controlador de punto de conexión de webhook para recibir solicitudes POST de datos de eventos.
- Prueba el controlador del punto de conexión de tu webhook a nivel local con la CLI de Stripe.
- Registra tu punto de conexión dentro de Stripe usando el Dashboard o la API.
- 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.
Crea un controlador
Configura una función de punto de conexión HTTP o HTTPS que pueda aceptar solicitudes de webhooks con un método POST. Si todavía estás desarrollando tu función de punto de conexión en una máquina local, puedes usar HTTP. Una vez que sea de acceso público, la función de punto de conexión de tu webhook debe usar HTTPS.
Configura tu función de punto de conexión para que haga lo siguiente:
- Maneje las solicitudes POST con una carga JSON que consista en un objeto Event.
- Devuelva 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 respuesta200
antes de registrar la factura del cliente como pagada en tu sistema contable.
Nota
Como alternativa, puedes crear una función de punto de conexión de webhook en tu lenguaje de programación con nuestro generador de puntos de conexión de webhooks.
Punto de conexión de ejemplo
Este fragmento de código es una función de webhook configurada para verificar que el tipo de evento se haya recibido, para manejar el evento y devolver una respuesta de 200.
Prueba tu controlador
Antes de pasar la función de punto de conexión de webhook a modo activo, te recomendamos que pruebes la integración de tu aplicación. Para hacerlo, debes configurar un oyente local para que envíe eventos a tu máquina local, y enviar eventos de prueba. Debes usar la CLI para las pruebas.
Reenvía eventos a un punto de conexión local
Para reenviar eventos a tu punto de conexión local, ejecuta el siguiente comando con la CLI a fin de configurar un oyente local. La marca --forward-to
envía todos los eventos de Stripe en modo de prueba a tu punto de conexión de webhook local.
stripe listen --forward-to localhost:4242/stripe_webhooks
Nota
También puedes ejecutar el comando de escucha de stripe en el Shell de Stripe para consultar los eventos a través de la terminal del shell de Stripe. Sin embargo, no podrás reenviar los eventos desde el shell a tu punto de conexión local.
Algunas configuraciones útiles para ayudarte a realizar pruebas con tu oyente local son las siguientes:
- Para deshabilitar la verificación del certificado HTTPS, utiliza la marca opcional
--skip-verify
. - Para reenviar solo eventos específicos, usa la marca opcional
--events
y especifica una lista de eventos separados por comas.
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \ --forward-to localhost:4242/webhook
- Para reenviar eventos a tu punto de conexión de webhook local desde el punto de conexión de webhook público que ya registraste en Stripe, usa la marca opcional
--load-from-webhooks-api
. Esta acción carga tu punto de conexión registrado, analiza la ruta y sus eventos registrados y, por último, agrega la ruta a tu punto de conexión de webhook local en--forward-to path
.
stripe listen --load-from-webhooks-api --forward-to localhost:5000
- Para comprobar las firmas de webhook, utiliza el
{{WEBHOOK_SIGNING_SECRET}}
de la salida inicial del comando de escucha.
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
Cómo activar eventos de prueba
Para enviar eventos de prueba, activa un tipo de evento al que está suscrito el destino de tu evento. Para hacerlo, crea manualmente un objeto a través del Dashboard de Stripe. Como alternativa, puedes usar el siguiente comando en el Shell de Stripe o CLI de Stripe.
Este ejemplo activa un evento payment_intent.succeeded
:
stripe trigger payment_intent.succeeded Running fixture for: payment_intent Trigger succeeded! Check dashboard for event details.
Nota
Cómo activar eventos con Stripe para VS Code.
Registra tu punto de conexión en Stripe
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.
Agrega un punto de conexión de webhook
Nota
Si habilitaste Workbench en tu cuenta, debes usar Workbench para registrar tu punto de conexión de webhook.
Stripe admite dos tipos de puntos de conexión, Account y Connect. Crea un punto de conexión de tipo Account excepto que ya hayas creado una aplicación Connect. Sigue estos pasos para registrar un punto de conexión de webhook en el Dashboard para desarrolladores. Puedes registrar hasta 16 puntos de conexión de webhooks en cada cuenta de Stripe.
- Ve a la página Webhooks.
- Haz clic en Agregar punto de conexión.
- Agrega la URL HTTPS de tu punto de conexión de webhook en URL del punto de conexión.
- Si tienes una cuenta de Stripe Connect, ingresa una descripción y haz clic en Escuchar eventos en las cuentas conectadas.
- Selecciona los tipos de eventos que recibes actualmente en tu punto de conexión de webhook local en Seleccionar eventos.
- Haz clic en Agregar punto de conexión.
Registra 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 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.
Asegura tu punto de conexión
Te recomendamos encarecidamente que asegures tu integración. Para eso, asegúrate de que su controlador verifique que todas las solicitudes de webhook son generadas por Stripe. Para la verificación, tienes dos opciones: verificar las firmas de webhook con nuestras bibliotecas oficiales o verificarlas manualmente.
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
Nota
Si habilitaste Workbench en tu cuenta, debes usar Workbench para gestionar tus 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.
Estado de webhook pendiente | Descripción | Solución |
---|---|---|
(Error al establecer conexión) ERR | No podemos establecer conexión con el servidor de destino. | Asegúrate de que tu dominio de host sea de acceso público en Internet. |
(302 ) ERR (u otro estado 3xx ) | El servidor de destino intentó redirigir la solicitud a otra ubicación. Consideramos las respuestas de redireccionamiento a las solicitudes de webhook como errores. | Establece el destino del punto de conexión del webhook en la URL resuelta por el redireccionamiento. |
(400 ) ERR (u otro estado 4xx ) | El servidor de destino no puede procesar la solicitud o no lo hará. Esta circunstancia puede darse cuando el servidor detecta un error (400 ), cuando la URL de destino tiene restricciones de acceso (401 , 403 ) o cuando la URL de destino no existe (404 ). |
|
(500 ) ERR (u otro estado 5xx ) | El servidor de destino encontró un error mientras se procesaba la solicitud. | Revisa los registros de tu aplicación para comprender por qué devuelve un error 500 . |
(Error TLS) ERR | No pudimos establecer una conexión segura con el servidor de destino. Estos errores suelen deberse a un problema con el certificado SSL/TLS o un certificado intermedio en la cadena de certificados del servidor de destino. | Realiza una prueba de servidor SSL para encontrar problemas que puedan causar este error. |
(Se agotó el tiempo de espera) ERR | El servidor de destino tardó demasiado en responder a la solicitud de webhook. | Asegúrate de aplazar la lógica compleja y devuelve una respuesta correcta de inmediato en tu código de manejo de webhooks. |
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 transmitir manualmente 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 cualquier 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 webhook pueden recibir ocasionalmente el mismo evento más de una vez. Para evitar la recepción de eventos duplicados, haz que el procesamiento de tu evento sea idempotente. Una forma de hacerlo es registrar los eventos que procesaste y, luego, no procesar los eventos ya registrados.
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.
Maneja los 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.
Recibe eventos con un servidor HTTPS
Si usas una URL HTTPS para tu punto de conexión de webhook, Stripe validará que la conexión con tu servidor sea segura antes de enviar tus datos de webhook. A fin de que esto funcione, tu servidor debe estar configurado correctamente para admitir HTTPS con un certificado de servidor válido. Las URL HTTPS son obligatorias en modo activo. Actualmente, los webhooks de Stripe no admiten TLS v1.3.
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 preestablecida 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 librerías 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:
- Recupera el secreto de tu punto de conexión.
- 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 punto de conexión 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.