Recibe eventos Stripe en tu punto de conexión de webhooks
Enviar eventos a tu cuenta de AWS
Estamos lanzando soporte para recibir eventos de Stripe en Amazon EventBridge en beta privada. Para obtener acceso anticipado, crea tu cuenta en eventbridge.stripe.dev.
Por qué usar 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.
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 webhooks 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, 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.
Resumen del evento
Stripe genera datos de eventos que podemos enviarte para informarte la actividad en tu cuenta.
Cuando se produce un evento, Stripe genera un nuevo objeto Event. Una única petición 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
.
Al registrar puntos de conexión de webhook en tu cuenta de Stripe, habilitas a Stripe para que envíe automáticamente objetos Event como parte de las peticiones POST al punto de conexión de webhook registrado alojado por tu aplicación. Después de que el punto de conexión de tu 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 al punto de conexión de tu webhook proporciona una instantánea del objeto que ha cambiado. Podría incluir 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
En el siguiente evento, se 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 de evento para comprender mejor los eventos y la información subyacente que proporcionan.
Tipo de evento
Recibes eventos para todos los tipos de eventos que el punto de conexión de tu webhook esté escuchando en tu configuración. Utiliza el type
de evento recibido para determinar qué procesamiento debe realizar tu petición. El data.object
correspondiente a cada type
de evento varía.
Modo activo y modo de prueba
Es posible que recibas peticiones de entrega de eventos en modo activo y en modo de prueba en tus puntos de conexión. Esta posibilidad podría darse si utilizas un único punto de conexión tanto para el modo activo como para el modo de prueba o si tienes una plataforma Connect que realiza peticiones en modo de prueba para cuentas conectadas Standard activas. Utiliza el atributo livemode
para verificar si el objeto existe en modo activo o de prueba y determinar el manejo correcto para el evento.
Versión de la API
La api_version
indica la versión de API del evento y determina la estructura del data.object incluido. Tu punto de conexión recibe eventos utilizando la versión de la API configurada, que puede diferir de la versión de la API predeterminada de tu cuenta o de la versión de la API de cualquier petición 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 de Java, .NET o Go, asegúrate de configurar la versión de la API del punto de conexión para que utilice la misma versión de la API anclada en el cliente. De lo contrario, es posible que no puedas deserializar 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 petición de API
Cuando se genera un evento como resultado de una petición de API, esa petición aparece como request.id
. Si usas una idempotency_key
al hacer la petición, esta se incluye como request.idempotency_key
. Marca este hash de request
cuando investigues qué causa un evento.
Objeto de datos y atributos anteriores
Para los eventos *.updated
, la carga del evento incluye data.previous_attributes
que te permiten inspeccionar qué ha cambiado en el objeto Stripe. El atributo previous_ attributes
en el ejemplo de evento customer.subscription.updated
anterior indica que la suscripción tiene un valor anterior de status: trialing
, entre otros cambios. El data.object
muestra el estado como active
, lo que indica que la suscripción ha finalizado el período de prueba.
Entregas pendientes
Utiliza pending_webhooks
para determinar cuántos puntos de conexión configurados para este evento no han respondido correctamente a la entrega. Durante la entrega inicial, este valor es 1 o superior porque tu punto de conexión no ha respondido correctamente. Si recuperas este evento más tarde, pending_webhooks
disminuirá a un mínimo de 0 a medida que cada punto de conexión responda correctamente. Esto es importante para los eventos invoice.created
porque las entregas fallidas pueden retrasar la finalización de la factura.
Eventos de cuenta conectada
Los eventos de las cuentas conectadas entregadas a un punto de conexión de Connect incluyen la account
. Usa account
para rastrear a qué cuenta conectada pertenece el objeto y asegurarte de que tu plataforma pueda procesar los datos del evento de manera adecuada.
Por qué se generan los objetos de evento
En esta tabla se describen diferentes escenarios que desencadenan la generación de objetos Event.
Fuente | Activar |
---|---|
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 a la API. |
API | Cuando activas 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 siguiendo los siguientes pasos:
- Crea un controlador de punto de conexión de webhooks para recibir peticiones de POST de datos de eventos.
- Prueba el controlador del punto de conexión de tu webhook a nivel local utilizando la CLI de Stripe.
- Registra tu punto de conexión dentro de Stripe utilizando el Dashboard o la API.
- Protege el punto de conexión de tu webhook.
Puedes registrarte y crear un punto de conexión para manejar varios tipos de eventos diferentes a la vez o configurar puntos de conexión particulares para eventos específicos.
Crear un controlador
Configura una función de punto de conexión HTTP o HTTPS que pueda aceptar peticiones de webhooks con un método POST. Si todavía estás desarrollando tu función de punto de conexión en tu máquina local, puedes usar HTTP. Después de que sea de acceso público, la función de punto de conexión de tu webhook debe usar HTTPS.
Configura la función de tu punto de conexión para que haga lo siguiente:
- Maneje las peticiones POST con una carga JSON que consiste en un objeto de evento.
- Devuelva 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 respuesta200
antes de actualizar 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 utilizando nuestro generador de puntos de conexión de webhooks interactivos.
Ejemplo de punto de conexión
Este fragmento de código es una función de webhook configurada para verificar que se haya recibido el tipo de evento, para manejar el evento y devolver una respuesta 200.
Prueba tu controlador
Antes de activar la función del punto de conexión de tu webhook, te recomendamos probar la integración de tu aplicación. Para hacerlo, configura un oyente local para que envíe eventos a tu máquina local y envia eventos de prueba. Debes usar la CLI para hacer una prueba.
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 para configurar un oyente local. El indicador --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 Stripe Shell para consultar los eventos a través de la terminal del shell de Stripe, aunque no podrás reenviar los eventos desde el shell a tu punto de conexión local.
Las configuraciones útiles para ayudarte a realizar una prueba con tu oyente local incluyen las siguientes:
- Para desactivar la verificación del certificado HTTPS, utiliza el indicador opcional
--skip-verify
. - Para reenviar solo eventos específicos, usa el indicador opcional
--events
e introduce 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 local de webhooks desde el punto de conexión público de webhooks que ya has registrado en Stripe, usa el indicador opcional
--load-from-webhooks-api
. Este carga tu punto de conexión registrado, analiza la ruta y sus eventos registrados y luego añade 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 del 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 creando manualmente un objeto a través del Dashboard de Stripe. También puedes usar el siguiente comando en Stripe Shell o la CLI de Stripe.
En este ejemplo se activa un evento payment_intent.succeeded
:
stripe trigger payment_intent.succeeded Running fixture for: payment_intent Trigger succeeded! Check dashboard for event details.
Nota
Aprende a activar eventos con Stripe for VS Code.
Registra tu punto de conexión en Stripe
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.
Añade un punto de conexión de webhook
Nota
Si has habilitado Workbench en tu cuenta, debes usar Workbench para registrar tu punto de conexión de webhook.
Stripe acepta dos tipos de puntos de conexión, Cuenta y Connect. Crea un punto de conexión para Cuenta a menos que hayas creado una aplicación Connect. Sigue los siguientes pasos para registrar un punto de conexión de webhook en el Dashboard para desarrolladores. Puedes registrar hasta 16 puntos de conexión de webhook en cada cuenta de Stripe.
- Dirígete a la página de Webhooks.
- Haz clic en Añadir punto de conexión.
- Añade la URL HTTPS de tu punto de conexión de tu webhook en URL del punto de conexión.
- Si tienes una cuenta Stripe Connect, introduce una descripción y haz clic en Escuchar eventos en las cuentas conectadas.
- Elige los tipos de eventos que recibes en la actualidad en el punto de conexión de tu webhook local en Elegir eventos.
- Haz clic en Añadir punto de conexión.
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.
Protege tu punto de conexión
Te recomendamos encarecidamente que protejas tu integración asegurándote de que tu controlador verifique que todas las peticiones de webhook sean generadas por Stripe. Puedes optar por verificar las firmas de webhook utilizando nuestras bibliotecas oficiales o verificarlas de forma manual.
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
Nota
Si has habilitado Workbench en tu cuenta, debes usar Workbench para gestionar las entregas de tus 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.
Estado del webhook pendiente | Descripción | Reparar |
---|---|---|
(No se ha podido conectar) ERR | No se puede establecer una conexión con el servidor de destino. | Asegúrate de que tu dominio de host sea de acceso público a Internet. |
(302 ) ERR (u otro estado 3xx ) | El servidor de destino ha intentado redirigir la petición a otra ubicación. Consideramos las respuestas de redireccionamiento a las peticiones de webhook como fallos. | Establece el destino del punto de conexión del webhook a la URL resuelta por el redireccionamiento. |
(400 ) ERR (u otro estado 4xx ) | El servidor de destino no puede o rechaza procesar la petición. Esto puede ocurrir 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 ha encontrado un error mientras procesaba la petición. | Revisa los registros de tu aplicación para comprender por qué está devolviendo un error 500 . |
(Error TLS) ERR | No hemos podido 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 del servidor SSL para descubrir los problemas que puedan causar este error. |
(Se ha agotado el tiempo de espera) ERR | El servidor de destino tardó demasiado en responder a la petición de webhook. | Asegúrate de diferir la lógica compleja y devolver una respuesta correcta de inmediato en tu código de gestión de webhooks. |
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 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
Ocasionalmente, los puntos de conexión de webhooks pueden recibir el mismo evento más de una vez. Para evitar el ingreso de eventos duplicados, haz que el procesamiento de eventos sea idempotente. Una manera de lograrlo consiste en registrar los eventos que ya has procesado y, a continuación, evitar procesar aquellos que ya están registrados.
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 reciba 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 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.
Recibe eventos con un servidor HTTPS
Si utilizas una URL HTTPS para el punto de conexión de tu webhook, 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. El modo activo requiere direcciones de URL HTTPS. Los webhooks de Stripe no son compatibles con TLS v1.3 en la actualidad.
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:
- 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. 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 y 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.