Ricevi gli eventi Stripe nell'endpoint del tuo webhook

Quando crei integrazioni Stripe, è probabile che tu voglia che le applicazioni ricevano gli eventi man mano che si verificano nei tuoi account Stripe, in modo che i sistemi di back-end possano eseguire le azioni in maniera adeguata.

Crea una destinazione dell’evento per ricevere eventi in un endpoint del webhook HTTPS. Dopo aver registrato un endpoint del webhook, Stripe può inviare i dati degli eventi in tempo reale all’endpoint del webhook della tua applicazione quando si verificano eventi nel tuo account Stripe. Stripe utilizza HTTPS per inviare eventi del webhook alla tua app come payload JSON che include un oggetto Event.

La ricezione di eventi webhook ti consente di rispondere a eventi asincroni, come quando la banca del cliente conferma un pagamento, un cliente contesta un addebito o si verifica un pagamento ricorrente.

Puoi anche ricevere eventi in Amazon EventBridge con le destinazioni dell’evento.

Inizia

Iniziare a ricevere eventi webhook nella tua app:

1. Crea un gestore dell’endpoint del webhook per ricevere le richieste POST dei dati degli eventi.
2. Testa localmente il gestore dell’endpoint del webhook utilizzando la CLI di Stripe.
3. Crea una nuova destinazione evento per il tuo endpoint del webhook.
4. Proteggi l’endpoint del webhook.

Puoi registrare e creare un endpoint per gestire diversi tipi di eventi contemporaneamente o impostare singoli endpoint per eventi specifici.

Comportamenti del tipo di evento non supportati per le destinazioni degli eventi dell’organizzazione

Stripe invia la maggior parte dei tipi di evento in modo asincrono; tuttavia, per determinati tipi di eventi, Stripe attende una risposta. Le azioni intraprese da Stripe in relazione a questi specifici tipi di eventi sono direttamente influenzate dalla ricezione o meno di una risposta dalla destinazione dell’evento.

Le destinazioni dell’organizzazione offrono un supporto limitato per i tipi di eventi che richiedono una risposta:

• Non puoi abbonarti a issuing_authorization.request per le destinazioni dell’organizzazione. Per iscriverti a questo tipo di evento, configura invece un endpoint del webhook in un account Stripe all’interno dell’organizzazione. Usa issuing_authorization.request per autorizzare le richieste di acquisto in tempo reale.
• Puoi abbonarti a checkout_sessions.completed per le destinazioni dell’organizzazione. Tuttavia, questo non gestisce il comportamento di reindirizzamento quando incorpori Checkout direttamente nel tuo sito web o reindirizzi i clienti a una pagina di pagamento in hosting su Stripe. Il recapito di un evento checkout_sessions.completed nella destinazione di un’organizzazione non influisce sul comportamento di reindirizzamento. Per influenzare il comportamento di reindirizzamento di Checkout, elabora questo tipo di evento con un endpoint del webhook configurato in un account Stripe all’interno dell’organizzazione.
• Puoi abbonarti a invoice.created per le destinazioni dell’organizzazione. Tuttavia, una risposta inadeguata a questo evento non influisce sulla finalizzazione automatica delle fatture quando si utilizza la riscossione automatica. Per influenzare la finalizzazione automatica delle fatture tramite le risposte dell’endpoint del webhook, elabora questo tipo di evento con un endpoint del webhook configurato in un account Stripe all’interno dell’organizzazione.

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Extract the context
  context = event.context

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

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

  api_key = account_api_keys[context]

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

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

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

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

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

  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

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

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

Registra il tuo endpoint

Dopo aver testato la funzione dell’endpoint del webhook, utilizza l’API o la scheda Webhook in Workbench per registrare l’URL accessibile dell’endpoint del webhook in modo che Stripe sappia dove consegnare gli eventi. Puoi registrare fino a 16 endpoint del webhook con Stripe. Gli endpoint dei webhook registrati devono essere URL HTTPS accessibili pubblicamente.

Formato URL webhook

Il formato dell’URL per registrare un endpoint del webhook è:

https://<your-website>/<your-webhook-endpoint>

Ad esempio, se il dominio è https://mycompanysite.com e il percorso verso l’endpoint del webhook è @app.route('/stripe_webhooks', methods=['POST']), specifica https://mycompanysite.com/stripe_webhooks come URL dell’endpoint.

Crea una destinazione di evento per il tuo endpoint del webhook

Crea la destinazione di un evento utilizzando Workbench nella Dashboard o a livello di codice con l’API. Puoi registrare fino a 16 destinazioni degli eventi su ciascun account Stripe.

Dashboard

API

Per creare un nuovo endpoint del webhook nella Dashboard:

1. Apri la scheda Webhook in Workbench.
2. Fai clic su Crea una destinazone dell’evento.
3. Seleziona la destinazione da cui vuoi ricevere gli eventi. Stripe supporta due tipi di configurazioni: Il tuo account e Account connessi. Seleziona Account per ascoltare gli eventi dal tuo account. Se hai creato un’applicazione Connect e vuoi ascoltare gli eventi dei tuoi account connessi, seleziona Account connessi.

Ascolta gli eventi da un endpoint del webhook dell'organizzazione

Se crei un endpoint del webhook in un account dell’organizzazione, seleziona Account per ascoltare gli eventi degli account della tua organizzazione. Se hai piattaforme Connect come membri delle tue organizzazioni e vuoi ascoltare gli eventi di tutti gli account connessi delle piattaforme, seleziona Account connessi.

1. Seleziona la versione API per l’oggetto di eventi che desideri utilizzare.
2. Seleziona i tipi di evento che vuoi inviare a un endpoint del webhook.
3. Seleziona Continua, quindi scegli Endpoint del webhook come tipo di destinazione.
4. Clicca su Continua, quindi fornisci l’URL dell’endpoint e una descrizione facoltativa per il webhook.

Registra un nuovo webhook utilizzando la scheda Webhook

Nota

Workbench sostituisce la Dashboard per sviluppatori esistente. Se stai ancora utilizzando la Dashboard per sviluppatori, scopri come creare un nuovo endpoint del webhook.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

Debug delle integrazioni del webhook

Durante la consegna di eventi all’endpoint del webhook, possono verificarsi diversi tipi di problemi:

• Stripe potrebbe non essere in grado di consegnare un evento all’endpoint del webhook.
• Potrebbe esserci un problema al certificato SSL dell’endpoint del webhook.
• La connettività di rete è intermittente.
• L’endpoint del webhook non riceve gli eventi che ti aspetti di ricevere.

Visualizza le consegne dell’evento

Per visualizzare le consegne degli eventi, seleziona l’endpoint del webhook in Webhook, quindi seleziona la scheda Eventi.

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.

Correggi i codici di stato HTTP

Quando per un evento viene visualizzato un codice di stato 200, vuol dire che è avvenuta la consegna all’endpoint del webhook. Potresti anche ricevere un codice di stato diverso da 200. Consulta la tabella riportata di seguito per un elenco dei codici di stato HTTP comuni e delle soluzioni consigliate.

Comportamenti di consegna degli eventi

Questa sezione ti aiuta a comprendere i vari comportamenti da aspettarsi per quanto riguarda il modo in cui Stripe invia gli eventi all’endpoint del webhook.

Tentativi automatici

Stripe tenta di consegnare gli eventi alla tua destinazione per un massimo di tre giorni con un ritardo di attesa esponenziale in modalità live. Visualizza la data del prossimo tentativo, se applicabile, nella scheda Consegne evento della destinazione dell’evento. Riproviamo le consegne degli eventi create in una sandbox tre volte nel corso di poche ore. Se la tua destinazione è stata disabilitata o eliminata durante un tentativo, impediamo futuri tentativi di quell’ evento. Tuttavia, se disabiliti e poi abiliti nuovamente la destinazione dell’evento prima che possiamo riprovare, vedrai comunque i tentativi futuri.

Tentativi manuali

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.

Ordine degli eventi

Stripe non garantisce la consegna degli eventi nell’ordine in cui sono stati generati. Ad esempio, la creazione di un abbonamento potrebbe generare i seguenti eventi:

• customer.subscription.created
• invoice.created
• invoice.paid
• charge.created (se esiste un addebito)

Assicurati che la destinazione dell’evento non dipenda dalla ricezione degli eventi in un ordine specifico. Preparati a gestire la consegna in modo appropriato. Puoi anche utilizzare l’API per recuperare eventuali oggetti mancanti. Ad esempio, se ricevi prima questo evento, puoi recuperare gli oggetti invoice, charge e subscription con le informazioni contenute in invoice.paidinvoice.paid’.

Controllo delle versioni dell’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.

Pratiche ottimali di utilizzo dei webhook

Rivedi queste pratiche ottimali per proteggere gli endpoint dei webhook e assicurarti che funzionino bene con la tua integrazione.

Gestisci gli eventi duplicati

A volte gli endpoint dei webhook potrebbero ricevere lo stesso evento più di una volta. Per proteggerti dalla ricezione di eventi duplicati, registra gli ID evento elaborati e poi non elaborare gli eventi già registrati.

In alcuni casi, vengono generati e inviati due oggetti Event separati. Per identificare questi duplicati, utilizza l’ID dell’oggetto in data.object e event.type.

Ascolta solo i tipi di evento richiesti dalla tua integrazione

Configura gli endpoint dei webhook per ricevere solo i tipi di eventi richiesti dalla tua integrazione. L’ascolto di altri eventi (o di tutti gli eventi) appesantisce inutilmente il server e pertanto è sconsigliato.

È possibile modificare gli eventi che un endpoint del webhook riceve attraverso la Dashboard o l’API.

Gestire gli eventi in modo asincrono

Configura il gestore per elaborare i prossimi eventi con una coda asincrona. Se scegli di elaborare gli eventi in modo sincrono, potrebbero verificarsi problemi di scalabilità. Un forte aumento delle consegne di webhook (ad esempio, all’inizio del mese, quando tutti gli abbonamenti vengono rinnovati) può sovraccaricare gli host degli endpoint.

Le code asincrone consentono di elaborare gli eventi simultanei a una velocità supportata dal sistema.

Percorso webhook esente dalla protezione CSRF

Se utilizzi Rails, Django o un altro framework web, il tuo sito potrebbe verificare automaticamente che ogni richiesta POST contenga un token CSRF. Questa importante misura di sicurezza consente di proteggere te e i tuoi utenti da eventuali tentativi di falsificazione della richiesta tra siti. Tuttavia, questa misura di sicurezza potrebbe anche impedire al sito di elaborare gli eventi legittimi. In tal caso, potrebbe essere necessario escludere il percorso dei webhook dalla protezione 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

Ricevi eventi con un server HTTPS

Se utilizzi un URL HTTPS per l’endpoint del webhook (obbligatorio in modalità live), prima di inviare i dati del webhook Stripe verifica che la connessione al tuo server sia sicura. Per eseguire questa procedura, il tuo server deve essere configurato correttamente per supportare il protocollo HTTPS e deve disporre di un certificato valido. I webhook di Stripe supportano solo le versioni v1.2 e v1.3 di TLS.

Genera endpoint per la chiave privata della firma digitale in maniera periodica

La chiave privata utilizzata per verificare che gli eventi provengano da Stripe è modificabile nella scheda Webhook di Workbench. Per tenere al sicuro le chiavi private, ti consigliamo di revocarle (modificarle) periodicamente o nei casi in cui sospetti che siano state compromesse.

Per generare una chiave:

1. Fai clic su ciascun endpoint nella scheda degli webhook di Workbench per cui vuoi generare la chiave.
2. Vai al menu extra () e fai clic su Revoca chiave privata. Puoi scegliere di far scadere immediatamente la chiave privata corrente o ritardarne la scadenza per 24 ore per darti il tempo di aggiornare il codice di verifica sul server. In quel periodo di tempo sono attive più chiavi private per l’endpoint. Stripe genera una firma per chiave privata fino alla scadenza.

Verifica che gli eventi siano inviati da Stripe

Stripe invia eventi webhook da un elenco predefinito di indirizzi IP. Considera attendibili solo gli eventi provenienti da tali indirizzi IP.

Verifica anche le firme dei webhook per confermare che Stripe abbia inviato gli eventi ricevuti. Stripe firma gli eventi webhook che invia agli endpoint aggiungendo una firma nell’intestazione Stripe-Signature di ogni evento. In questo modo puoi verificare che gli eventi siano stati inviati da Stripe e non da una terza parte. Puoi verificare le firme utilizzando le nostre librerie ufficiali, oppure manualmente con una tua soluzione.

La sezione seguente descrive come verificare le firme dei webhook:

1. Recuperando la chiave privata del tuo endpoint.
2. Verificando la firma.

Recuperare la chiave privata del tuo endpoint

Utilizza Workbench e vai alla scheda Webhook per visualizzare tutti gli endpoint. Seleziona un endpoint per il quale vuoi ricevere la chiave privata e poi fai clic sul pulsante Fai clic per visualizzare.

Stripe genera una chiave privata unica per ogni endpoint. Se utilizzi lo stesso endpoint per le chiavi API di test e live, la chiave privata è diversa per ogni modalità. Inoltre, se utilizzi più endpoint, per verificare le firme devi richiedere una chiave privata per ognuno di essi. Dopo questa configurazione, Stripe inizia a firmare ogni webhook che invia all’endpoint.

Impedire gli attacchi di tipo replay

Un attacco di tipo replay si verifica quando un utente malintenzionato intercetta un paylod valido e la sua firma e poi li ritrasmette. Per mitigare questi attacchi, Stripe include un timestamp nell’intestazione Stripe-Signature. Dato che il timestamp fa parte del payload firmato, viene anch’esso verificato dalla firma: quindi un utente malintenzionato non può modificare il timestamp senza invalidare la firma. Se la firma è valida ma il timestamp è troppo vecchio, puoi fare in modo che la tua applicazione rifiuti il payload.

Le nostre librerie hanno una tolleranza predefinita di 5 minuti tra il timestamp e l’ora corrente. Per modificarla, devi specificare un ulteriore parametro quando verifichi le firme. Utilizza il Network Time Protocol (NTP) per garantire che l’orologio del server sia preciso e sincronizzato con l’ora dei server di Stripe.

Stripe genera il timestamp e la firma di ogni evento inviato all’endpoint. Se Stripe tenta di inviare di nuovo un evento, ad esempio perché in precedenza l’endpoint aveva risposto con un codice di stato non 2xx, vengono generati una nuova firma e un nuovo timestamp per il nuovo tentativo di consegna.

Restituisci rapidamente una risposta 2xx

L’endpoint deve restituire rapidamente un codice di stato riuscito (2xx) prima che l’esecuzione di qualsiasi logica complessa possa causare un timeout. Ad esempio, è necessario restituire una risposta 200 prima che la fattura di un cliente venga aggiornata come pagata nel sistema contabile.