# Handle payment events with webhooks

How to use webhooks to respond to offline payment events.

Un *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) è un endpoint HTTP che riceve gli eventi da Stripe.

I webhook ti consentono di ricevere notifiche sugli eventi di pagamento che si verificano al di fuori del tuo flusso di pagamento come:

- Pagamenti riusciti (`payment_intent.succeeded`)
- Pagamenti contestati (`charge.dispute.created`)
- Saldo disponibile nel tuo account Stripe (`balance.available`)

Anche se la Dashboard è in grado di gestire perfettamente operazioni una tantum quali il rimborso di un pagamento o l’aggiornamento delle informazioni di un cliente, i webhook sono utili per sviluppare l’integrazione dei pagamenti e consentono di elaborare un elevato volume di eventi critici.

## Sviluppa un tuo webhook

Puoi creare un gestore di webhook sul tuo server per gestire tutti i flussi di pagamento offline. Innanzitutto scegli un endpoint in grado di ricevere le richieste provenienti da Stripe e utilizza la CLI per verificare localmente la tua integrazione. Ogni richiesta di Stripe contiene un oggetto [Event](https://docs.stripe.com/api/events/object.md) con un riferimento all’oggetto su Stripe che è stato modificato.

## Crea un endpoint del webhook

Aggiungi un nuovo endpoint alla tua applicazione. Per rispondere a determinati eventi, verifica il campo `type` dell’oggetto dell’evento inviato nel corpo della richiesta. Quindi scegli l’output standard per assicurarti che il webhook funzioni.

Avvia il tuo server dopo aver aggiunto il nuovo endpoint.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

require 'stripe'
require 'sinatra'
require 'json'

# Using the Sinatra framework
set :port, 4242

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
    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
```

## Installare e configurare la CLI di Stripe
Per ulteriori opzioni di installazione, consulta la sezione [Iniziare a usare la CLI di Stripe](https://docs.stripe.com/stripe-cli.md).
Una volta installata la CLI di Stripe, esegui `stripe login` nella riga di comando per generare un codice di associazione da collegare al tuo account Stripe. Premi **Invio** per avviare il browser e accedere al tuo account Stripe per consentire l’accesso. La chiave API generata è valida 90 giorni. Puoi modificarla o eliminarla nella sezione [Chiavi API](https://dashboard.stripe.com/apikeys) nella Dashboard.

> Puoi creare una configurazione specifica del progetto includendo il flag [–project-name](https://docs.stripe.com/cli/login#login-project-name) quando accedi e quando esegui i comandi per quel progetto.

Test

```bash
stripe login
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

Se vuoi utilizzare una chiave API esistente, utilizza il flag `--api-key`:

```bash
stripe login --api-key <<YOUR_SECRET_KEY>>
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

## Verifica un webhook localmente

Utilizza la CLI per inoltrare gli eventi al tuo endpoint del webhook locale utilizzando il comando `listen`.

Se la tua applicazione viene eseguita sulla porta 4242, esegui il seguente comando:

```bash
stripe listen --forward-to http://localhost:4242/webhook
```

In un’altra scheda del terminale, utilizza il comando `trigger` della CLI per attivare un evento webhook fittizio.

```bash
stripe trigger payment_intent.succeeded
```

Il seguente evento appare nella scheda `listen`:

```bash
[200 POST] OK payment_intent.succeeded
```

“Il PaymentIntent è andato a buon fine” viene visualizzato nella scheda del terminale del tuo server.

## Optional: Verifica la firma del webhook

Stripe include una firma nell’intestazione `Stripe-Signature` di ogni evento. In questo modo puoi accertarti che gli eventi siano stati inviati da Stripe e non da una terza parte. Puoi verificare le firme utilizzando le librerie ufficiali o [verificare le firme manualmente](https://docs.stripe.com/webhooks.md#verify-manually) con una tua soluzione.

Innanzitutto, cerca la chiava privata dell’endpoint del webhook e aggiungila al gestore dei webhook come `endpoint_secret`. Dato che utilizzi ancora la CLI di Stripe per sviluppare il tuo endpoint localmente, utilizza il comando `trigger` per generare dalla CLI una chiave privata dell’endpoint del webhook.

```bash
stripe listen
```

La chiave privata dell’endpoint del webhook inizia con `whsec_` ed è seguita da una serie di numeri e lettere. Conserva questa chiave privata dell’endpoint del webhook in un luogo sicuro e non mostrarla mai pubblicamente.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

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 Dashboardendpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

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

  beginevent = 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
```

## Distribuisci l'endpoint del webhook

Quando avrai la possibilità di distribuire l’endpoint del webhook nell’ambiente di produzione, dovrai procedere come segue:

1. Utilizza le tue [chiavi API in modalità live](https://docs.stripe.com/keys.md#test-live-modes) e non quelle di test.
1. Configura il tuo webhook endpoint in [Workbench](https://docs.stripe.com/workbench.md) o con l’API.
1. Per configurare il tuo endpoint in Workbench, vai alla scheda [Webhook](https://dashboard.stripe.com/workbench/webhooks).
1. Fai clic su **Aggiungi destinazione** e inserisci la versione dell’API Stripe e gli eventi specifici che desideri che Stripe invii. Fai clic su **Continua** e seleziona **Endpoint webhook** dall’elenco dei tipi di destinazione disponibili. Fai clic su **Continua** e inserisci l’URL del tuo endpoint, un nome facoltativo e una descrizione facoltativa. Fai clic su **Crea destinazione**.
1. Sostituisci il segreto dell’endpoint webhook nella tua applicazione con il nuovo segreto visualizzato nella vista dei dettagli della destinazione in Workbench per il tuo endpoint.

La tua applicazione è pronta per accettare gli eventi in modalità live. Per ulteriori informazioni sulla configurazione dell’endpoint del webhook, consulta la sezione sull’API [Webhook Endpoint](https://docs.stripe.com/api/webhook_endpoints.md). Per i test in una sandbox, [consulta la nostra Guida allo sviluppo](https://docs.stripe.com/webhooks.md).