Ricevere eventi Stripe nell'endpoint del webhook

Quando crei integrazioni Stripe, è consigliabile 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 è particolarmente utile per gli eventi asincroni, come quando la banca del cliente conferma un pagamento, un cliente contesta un addebito, un pagamento ricorrente va a buon fine o vengono riscossi pagamenti in abbonamento.

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

Per iniziare

Per iniziare a ricevere eventi del webhook nella tua app, crea e registra un endpoint del webhook:

1. Crea un gestore di endpoint del webhook per ricevere richieste POST dei dati degli eventi.
2. Verifica localmente il gestore di endpoint del webhook utilizzando la CLI di Stripe.
3. Registra il tuo endpoint in Stripe utilizzando la Dashboard o l’API.
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.

require 'json'

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

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

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

  status 200
end

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

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

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

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

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

Registra il tuo endpoint

Dopo aver testato la funzione dell’endpoint del webhook, registra l’URL accessibile dell’endpoint del webhook utilizzando la sezione Webhook nella Dashboard per gli sviluppatori o l’API in modo che Stripe sappia dove consegnare gli eventi. Stripe ti consente di registrare fino a 16 endpoint del webhook. Gli endpoint del webhook registrati devono essere URL HTTPS accessibili pubblicamente.

Formato dell’URL del webhook

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

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

Ad esempio, se il tuo 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 un nuovo endpoint del webhook

You can create new event destinations for webhook and AWS EventBridge destinations.

1. Open the Event destinations tab in Workbench.
2. Click Create new destination.
3. Select the API version for the events object you want to consume.
4. If you’re using Connect, you can listen for Events on connected accounts. Otherwise, choose Events on your account.
5. Select the event types that you want to send to the destination, then click Continue.
6. Select Webhook to send events to an HTTPS endpoint.
7. Provide the Endpoint URL for Stripe to send webhooks to and an optional description for the endpoint.
8. Click Create destination to create your webhook endpoint.

Nota

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

Registra un endpoint del webhook con l’API di Stripe

Puoi anche creare endpoint dei webhook a livello di codice.

Per ricevere eventi dagli account connessi, utilizza il parametro connect.

Il seguente esempio mostra come creare un endpoint che ti informa dell’esito positivo o negativo degli addebiti.

Command Line

curl

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "url"="https://example.com/my/webhook/endpoint" \
  -d "enabled_events[]"="payment_intent.payment_failed" \
  -d "enabled_events[]"="payment_intent.succeeded"

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

require 'stripe'
require 'sinatra'

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

# Using the Sinatra framework
set :port, 4242

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

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

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

  status 200
end

Eseguire il debug delle integrazioni dei 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.

Visualizzare le consegne dell’evento

Per visualizzare le consegne degli eventi per un endpoint specifico, seleziona l’endpoint del webhook nella scheda Webhook.

Per visualizzare tutti gli eventi attivati nel tuo account, consulta la scheda Eventi.

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

Ripetizione del comportamento

In modalità live, Stripe cerca di consegnare un determinato evento all’endpoint del webhook per un massimo di 3 giorni con un ritardo di attesa esponenziale. Nella sezione Eventi della Dashboard, puoi visualizzare quando verrà ripetuto il tentativo successivo.

In modalità di test, Stripe esegue tre tentativi nell’arco di alcune ore. Dopo questo periodo di tempo, puoi eseguire questi tentativi per i webhook manualmente utilizzando la sezione Eventi della Dashboard. Inoltre, puoi inviare query per gli eventi persi al fine di riconciliare i dati per un periodo di tempo qualsiasi.

I tentativi automatici proseguono, anche se riprovi la trasmissione manuale di eventi di webhook singoli a un determinato endpoint e il tentativo ha esito positivo.

Se l’endpoint viene disabilitato o eliminato durante un tentativo di Stripe, eventuali futuri tentativi di quell’evento vengono impediti. Tuttavia, se disabiliti e poi abiliti nuovamente un endpoint del webhook prima che Stripe possa riprovare, puoi comunque visualizzare i tentativi futuri.

Disabilitazione del comportamento

In modalità di test e live, Stripe cercherà di segnalarti via email un endpoit non configurato correttamente in caso di mancata risposta con codice di stato HTTP 2xx per più giorni di fila. Nell’email viene indicato anche quando l’endpoint verrà disabilitato automaticamente.

Controllo delle versioni dell’API

Quando si verifica l’evento, la versione dell’API nelle impostazioni dell’account determina la versione dell’API e la struttura di un oggetto Event inviato in un webhook. Ad esempio, se l’account è impostato su una versione dell’API precedente, ad esempio 2015-02-16, e si modifica la versione dell’API per una richiesta specifica con controllo delle versioni, l’oggetto Event generato e inviato all’endpoint è ancora basato sulla versione dell’API 2015-02-16.

Non è possibile modificare gli oggetti Event dopo la creazione. Ad esempio, se un addebito viene aggiornato, quello originale rimane invariato. Di conseguenza gli aggiornamenti successivi della versione dell’API dell’account non modificano in modo retroattivo gli oggetti Event esistenti. Anche il recupero di oggetti Event precedenti chiamando /v1/events con una versione più recente dell’API non influisce sulla struttura degli eventi ricevuti.

Puoi impostare gli endpoint dei webhook sulla versione predefinita o su quella più recente dell’API. L’oggetto Event inviato all’URL del webhook è strutturato in funzione della versione specifica dell’endpoint. Puoi anche creare endpoint a livello di codice con un parametro api_version.

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)

L’endpoint non deve aspettarsi la consegna degli eventi in quest’ordine e quindi deve gestire le consegne in modo appropriato. Puoi anche utilizzare l’API per recuperare eventuali oggetti mancanti. Ad esempio, puoi recuperare gli oggetti Invoice, Charge e Subscription utilizzando le informazioni contenute nell’evento invoice.paid, se l’hai ricevuto per primo.

Pratiche ottimali di utilizzo dei webhook

Rivedi le pratiche ottimali per proteggere i webhook e garantirne il corretto funzionamento nella tua integrazione.

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

Ascoltare solo i tipi di evento richiesti dall’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 ti consentono di elaborare gli eventi simultanei a una velocità che il tuo sistema è in grado di supportare.

Esentare il percorso dei webhook 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

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

Revocare periodicamente le chiavi private della firma digitale

La chiave privata utilizzata per verificare gli eventi provenienti da Stripe è modificabile nella sezione Webhook della Dashboard. Per ogni endpoint, 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. Per tenere al sicuro le chiavi private, ti consigliamo di revocarle (modificarle) periodicamente o nei casi in cui sospetti che siano state compromesse.

Verificare che gli eventi provengano da Stripe

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

Inoltre, verifica le firme dei webhook per confermare che gli eventi ricevuti siano inviati da Stripe. 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 verificarle 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 dell’endpoint

Utilizza la sezione Webhook della Dashboard. Seleziona un endpoint per il quale vuoi ricevere la chiave privata. La chiave privata viene visualizzata in alto a destra della pagina.

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. In questo modo, 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 diverso da 2xx, per il nuovo tentativo di consegna vengono generati una nuova firma e un nuovo timestamp.

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