# Gestisci gli eventi di pagamento con i webhook

Utilizzare i webhook per rispondere agli eventi di pagamento online

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

Installa la CLI di Stripe con [npm](https://www.npmjs.com/):

```bash
npm install --global @stripe/cli
```

> Per ulteriori opzioni di installazione per Windows, macOS, Linux e Docker, consulta il [readme della CLI di Stripe](https://github.com/stripe/stripe-cli#installation) su GitHub.

Dopo l’installazione, collega la CLI al tuo account Stripe effettuando l’accesso:

```bash
stripe login
```

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

## 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.
2. Configura il tuo webhook endpoint in [Workbench](https://docs.stripe.com/workbench.md) o con l’API.
3. Per configurare il tuo endpoint in Workbench, vai alla scheda [Webhook](https://dashboard.stripe.com/workbench/webhooks).
4. 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**.
5. 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).