Ir a contenido
Crea una cuenta
 o
Inicia sesión
Logotipo de Stripe Docs
/
Crear una cuenta
Iniciar sesión

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

Escucha eventos en tu cuenta de Stripe en el punto de conexión de tu webhook para que tu integración pueda activar reacciones automáticamente.

Copiar página

Envía eventos a tu cuenta de AWS

Ahora puedes enviar eventos directamente a Amazon EventBridge como destino de eventos.

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 acciones en consecuencia.

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 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 empezar a recibir eventos de webhook en tu aplicación, sigue estos pasos:

  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. Crea un nuevo destino de evento para tu punto de conexión de webhooks.
  4. Protege 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.

Comportamientos de tipo de evento no admitidos para destinos de eventos de una 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 respuesta del destino del evento o la falta de ella modifican directamente las acciones de Stripe con respecto a estos tipos de eventos específicos.

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

  • No puedes suscribirte a issuing_authorization.request para los destinos de la organización. En su lugar, configura un punto de conexión de webhook en una cuenta de Stripe dentro de la organización para suscribirte a este tipo de evento. Usa issuing_authorization.request para autorizar 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á el comportamiento de redireccionamiento. Para modificar 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, la respuesta efectuada en forma incorrecta a este evento no influye en la finalización automática de facturas cuando se usa el cobro automático. Para modificar la finalización automática de las facturas a través de 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.

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:

  1. Maneje las solicitudes POST con una carga JSON que consista en un objeto Event.
  2. En el caso de los controladores de eventos de organización, busca el valor context para determinar qué cuenta de una organización generó el evento y, luego, establece el encabezado Stripe-Context correspondiente al valor context.
  3. Devuelve 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.

Nota

Como alternativa, puedes crear una función de punto de conexión de webhook en tu lenguaje de programación con nuestro generador interactivo 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 los eventos recibidos de una cuenta de Stripe, controlar los eventos y devolver respuestas 200. Refiérete al controlador de eventos con instantánea cuando uses recursos de la API v1 y refiérete al controlador de eventos breves cuando uses recursos de la API v2.

Al crear un controlador de eventos con instantánea, usa la definición del objeto API en el momento del evento para la lógica. Para ello, accede a los campos data.object del evento. También puedes recuperar el recurso API de la API de Stripe para acceder a la definición de objeto más reciente y actualizada.

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

Ejemplo de controlador de organización

Este fragmento de código es una función del punto de conexión de webhook configurada para verificar los eventos recibidos en toda una organización, controlar los eventos y devolver respuestas 200. El controlador comprueba a qué cuentas se aplica el evento recibido comprobando el campo context en la carga del evento y, luego, utiliza las claves adecuadas de API de la cuenta para las llamadas API posteriores en la cuenta.

This code snippet is a webhook function configured to check for received events, detect the originating account if applicable, handle the event, and return a 200 response.

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

Prueba tu controlador

Antes de pasar a modo activo la función de punto de conexión de webhook, 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.

Reenviar 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 y configura un oyente local. La marca --forward-to envía todos los eventos de Stripe en un entorno de prueba a tu punto de conexión local de webhook. Usa los comandos de CLI adecuados que se indican a continuación en función de si utilizas eventos breves o eventos con instantánea.

Usa el siguiente comando para reenviar eventos con instantánea al oyente local.

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

Nota

También puedes ejecutar stripe listen para ver los eventos en el shell de Stripe, aunque no podrás reenviar 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.

Usa el siguiente comando para reenviar eventos con instantánea específicos al oyente local.

Command Line
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.

Usa el siguiente comando para reenviar eventos con instantánea desde un punto de conexión de webhook público al oyente local.

Command Line
stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook
  • 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

To send test events, trigger an event type that your event destination is subscribed to by manually creating an object in the Stripe Dashboard. Learn how to trigger events with Stripe for VS Code.

You can use the following command in either Stripe Shell or Stripe CLI. This example triggers a payment_intent.succeeded event:

Command Line
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 del webhook, usa la API o la pestaña Webhooks en Workbench para registrar la URL accesible del punto de conexión del webhook de forma que Stripe sepa dónde entregar 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.

Crea un destino de evento para el punto de conexión del 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.

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 deseas recibir eventos. Stripe admite dos tipos de configuraciones: Tu cuenta y Cuentas conectadas. Selecciona Cuenta para escuchar los eventos de tu propia cuenta. Si creaste 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 webhook 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 de 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 API para el objeto Events que quieres consumir.
  2. Selecciona los tipos de eventos que quieras enviar a un punto de conexión de webhook.
  3. Selecciona Continuar y, luego, Punto de conexión del webhook como el tipo de destino.
  4. Haz clic en Continuar y, luego, proporciona la URL del punto de conexión y una descripción opcional del webhook.
Registra un nuevo webhook con la pestaña Webhooks

Registra un nuevo webhook con la pestaña Webhooks

Nota

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

Protege tu punto de conexión

Tienes que proteger tu integración. Para hacerlo, asegúrate de que tu controlador verifique que todas las solicitudes de webhook sean generadas por Stripe. Puedes verificar las firmas de webhooks con nuestras bibliotecas oficiales o hacerlo manualmente.

Haz la verificación manual de las firmas de webhook con las bibliotecas oficiales

Recomendamos utilizar nuestras bibliotecas oficiales para verificar las firmas. Para realizar la verificación, proporciona la carga del evento, el encabezado Stripe-Signature y el secreto del punto de conexión. Si la verificación falla, verás un error.

Si recibes un error de verificación de firma, lee nuestra guía sobre solución de problemas.

Advertencia

Stripe requiere que el cuerpo sin formato de la solicitud realice la verificación de la firma. Si estás usando un framework, asegúrate de que no manipule el cuerpo sin formato. Cualquier manipulación al cuerpo sin formato de la solicitud hará que la verificación falle.

# 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 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.
  • El punto de conexión de tu webhook podría tener 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.

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

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 pendienteDescripciónCorregir
(Error al establecer conexión) ERRNo 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).
  • Asegúrate de que tu punto de conexión sea de acceso público en Internet.
  • Asegúrate de que tu punto de conexión acepte un método POST HTTP.
(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) ERRNo pudimos establecer una conexión segura con el servidor de destino. Estos errores suelen deberse a los problemas con el certificado SSL/TLS o un certificado intermedio en la cadena de certificados del servidor de destino. Stripe requiere una versión v1.2 de TLS o superior.Realiza una prueba de servidor SSL para encontrar problemas que puedan causar este error.
(Se agotó el tiempo de espera) ERREl 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

Esta sección te ayuda a 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.

Reintentos automáticos

Stripe intenta entregar eventos en tu destino durante un máximo de tres días con un retroceso exponencial en modo activo. Consulta cuándo se hará el siguiente reintento, si corresponde, en la pestaña Entregas de eventos de tu destino de eventos. Reintentamos las entregas de eventos creadas en un entorno de prueba tres veces en el transcurso de unas pocas horas. Si tu destino se deshabilitó o se eliminó cuando realizamos un reintento, no permitiremos próximos reintentos. Sin embargo, si deshabilitas y, luego, vuelves a habilitar el destino del evento antes de que podamos reintentarlo, aún verás reintentos futuros.

Reintentos manuales

Unsupported for Amazon EventBridge

You can’t manually resend events to Amazon EventBridge.

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.

Pedido de eventos

Stripe no garantiza la entrega de eventos en el orden en que se generaron. Por ejemplo, crear 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 recibir los eventos en un orden específico. Prepárate para administrar la entrega de manera adecuada. También puedes usar la API para recuperar los objetos faltantes. 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 la 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.

Prácticas recomendadas para usar webhooks

Revisa estas prácticas recomendadas para asegurarte de que tus puntos de conexión de webhook sigan siendo seguros y funcionen bien 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 el controlador para procesar los eventos entrantes con una cola asincrónica. Es posible que tengas problemas de escalabilidad si decides procesar los eventos de forma sincrónica. Cualquier aumento importante en las entregas de webhooks (por ejemplo, durante el comienzo del mes, cuando se renuevan todas las suscripciones) podría sobrecargar a los hosts de los puntos de conexión.

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

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 provienen de Stripe se puede modificar en la pestaña Webhooks de Workbench. Para mantenerlos seguros, te recomendamos que cambies los secretos periódicamente o cuando sospeches que un secreto está en peligro.

Para cambiar un secreto:

  1. Haz clic en cada punto de conexión de la pestaña Webhooks de Workbech para el que desees aplicar el secreto.
  2. Ve al menú de contenido adicional () y haz clic en Cambiar secreto. Puedes elegir que el secreto actual venza de inmediato o postergar 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.

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.

Verifica también las firmas de webhook para confirmar que Stripe envió los eventos recibidos. Stripe firma los eventos de webhook que envía a tus puntos de conexión con una firma en el encabezado Stripe-Signature de cada evento. Esto te permite comprobar que los eventos fueron enviados por Stripe y no por terceros. Puedes verificar las firmas con nuestras bibliotecas oficiales o hacer la verificación 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 Workbench y navega a la pestaña Webhooks para ver todos los puntos de conexión. Selecciona un punto de conexión para el que desees obtener el secreto y, a continuación, haz clic en Hacer clic para revelar.

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. Después de esta configuración, 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.

Errores habituales

No uses un valor de tolerancia 0. El uso de un valor de tolerancia 0 deshabilita por completo la comprobación reciente.

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.

Consulta también

¿Te fue útil esta página?
SíNo
¿Necesitas ayuda? Ponte en contacto con soporte.
Únete a nuestro programa de acceso anticipado.
Echa un vistazo a nuestro registro de cambios.
¿Tienes alguna pregunta? Contacto.
¿LLM? Lee llms.txt.
Con tecnología de Markdoc