# Ricevi gli eventi Stripe nell'endpoint del tuo webhook

Ascolta gli eventi di Stripe sul tuo endpoint webhook così la tua integrazione può attivare automaticamente le reazioni.

Puoi creare un endpoint webhook HTTPS per ricevere eventi. Dopo aver registrato un endpoint webhook, Stripe invia dati in tempo reale a tale endpoint quando nel tuo account Stripe si verificano [eventi](https://docs.stripe.com/event-destinations.md#events-overview). Stripe utilizza HTTPS per inviare gli eventi webhook alla tua app come payload JSON contenente informazioni sull’evento.

La ricezione degli eventi webhook ti aiuta a rispondere a eventi asincroni, come quando la banca di un cliente conferma un pagamento, un cliente contesta un addebito o un pagamento ricorrente va a buon fine.

Puoi anche utilizzare gli eventi Stripe nella tua infrastruttura AWS o Azure inviandoli direttamente ad [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md) o ad [Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md).

Completa i passaggi riportati di seguito per iniziare a ricevere eventi webhook nella tua app. Puoi registrare un unico endpoint per gestire contemporaneamente diversi tipi di evento oppure configurare endpoint individuali per eventi specifici.

## Configura il tuo endpoint

Utilizza l’[API](https://docs.stripe.com/api/v2/event-destinations.md) o la scheda [Webhook](https://dashboard.stripe.com/webhooks) in Workbench per registrare l’URL accessibile del tuo endpoint webhook, in modo che Stripe sappia dove recapitare gli eventi. Puoi registrare fino a 16 endpoint webhook con Stripe. Gli endpoint webhook registrati devono avere URL HTTPS accessibili pubblicamente.

- Se disponi di un server localhost ma non hai un URL HTTPS accessibile pubblicamente, puoi utilizzare uno strumento di tunneling come [ngrok](https://ngrok.com/) per generare un URL HTTPS temporaneo accessibile pubblicamente da utilizzare a scopo di test.
- In alternativa, puoi [eseguire test in locale utilizzando la CLI di Stripe](https://docs.stripe.com/webhooks.md#local-listener) prima di registrare un URL HTTPS accessibile pubblicamente.

### Formato URL 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 del tuo endpoint 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

#### Dashboard

Per creare un nuovo endpoint del webhook nella Dashboard:

1. Apri la scheda [Webhook](https://dashboard.stripe.com/webhooks) in Workbench.
2. Fai clic su **Crea una destinazione di eventi**.
3. Seleziona **Il tuo account** per intercettare gli eventi provenienti dal tuo account.
4. Seleziona la versione dell’API per l’[oggetto evento](https://docs.stripe.com/api/events.md) che desideri utilizzare.
5. Seleziona i [tipi di evento](https://docs.stripe.com/api/events/types.md) che desideri inviare a un endpoint webhook.
6. Seleziona **Continua**, quindi scegli **Endpoint webhook** come tipo di destinazione.
7. Fai clic su **Continua**, quindi fornisci l’**URL dell’endpoint** e una descrizione facoltativa per il webhook.
8. Nella pagina delle impostazioni del webhook viene visualizzato un segreto di firma che inizia con `whsec_`. Fai clic su **Rivela segreto** e copia il valore da utilizzare quando [crei un gestore](https://docs.stripe.com/webhooks.md#webhook-endpoint-def).

> [Workbench](https://docs.stripe.com/workbench.md) sostituisce la [Dashboard per sviluppatori](https://docs.stripe.com/development/dashboard.md) esistente. Puoi comunque [creare un nuovo endpoint webhook](https://docs.stripe.com/development/dashboard/webhooks.md) nella Dashboard per sviluppatori, anche se consigliamo di utilizzare Workbench.

#### API

Utilizza l’endpoint [/v2/core/event_destinations](https://docs.stripe.com/api/v2/event-destinations.md) per registrare un nuovo endpoint.

#### Eventi istantanei

Per ricevere [eventi salienti](https://docs.stripe.com/api/events/types.md) dal tuo account, imposta il valore di [event_payload](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-event_payload) su `snapshot` e il valore di [enabled_events](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-enabled_events) sui tipi di evento che desideri inviare all’endpoint webhook:

```curl
curl -X POST https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-08-26.preview" \
  --json '{
    "name": "My event destination",
    "type": "webhook_endpoint",
    "events_from": [
        "@self"
    ],
    "event_payload": "snapshot",
    "enabled_events": [
        "payment_intent.succeeded",
        "payment_intent.payment_failed"
    ],
    "webhook_endpoint": {
        "url": "https://mycompanysite.com/webhook"
    },
    "include": [
        "webhook_endpoint.signing_secret"
    ]
  }'
```

L’output contiene un valore `webhook_endpoint.signing_secret` che inizia con `whsec_`. Copia questo valore da utilizzare quando [crei un gestore](https://docs.stripe.com/webhooks.md#webhook-endpoint-def).

#### Eventi thin

Se utilizzi [eventi leggeri](https://docs.stripe.com/api/v2/core/events/event-types.md), devi registrare un endpoint webhook separato. Scopri di più sulle [differenze tra eventi leggeri ed eventi salienti](https://docs.stripe.com/event-destinations.md#events-overview).

Per ricevere [eventi leggeri ](https://docs.stripe.com/api/v2/core/events/event-types.md) dal tuo account, imposta il valore di [event_payload](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-event_payload) su `thin` e il valore di [enabled_events](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-enabled_events) sui tipi di evento che desideri inviare all’endpoint webhook:

```curl
curl -X POST https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-08-26.preview" \
  --json '{
    "name": "My event destination",
    "type": "webhook_endpoint",
    "events_from": [
        "@self"
    ],
    "event_payload": "thin",
    "enabled_events": [
        "v1.billing.meter.error_report_triggered"
    ],
    "webhook_endpoint": {
        "url": "https://mycompanysite.com/webhook"
    },
    "include": [
        "webhook_endpoint.signing_secret"
    ]
  }'
```

L’output contiene un valore `webhook_endpoint.signing_secret` che inizia con `whsec_`. Copia questo valore da utilizzare quando [crei un gestore](https://docs.stripe.com/webhooks.md#webhook-endpoint-def).

### Esegui test in locale senza un URL registrato

Se non disponi di un URL HTTPS accessibile pubblicamente e registrato, puoi testare i webhook in locale utilizzando la CLI di Stripe per [inoltrare gli eventi al tuo endpoint locale](https://docs.stripe.com/cli/use-cli#forward-events-to-your-local-webhook-endpoint):

1. Se non l’hai ancora fatto, [installa la CLI di Stripe](https://docs.stripe.com/cli/install) sul tuo computer.

2. Accedi al tuo account Stripe e configura la CLI eseguendo `stripe login` dalla riga di comando.

3. Consenti al tuo host locale di ricevere un evento simulato eseguendo [stripe listen](https://docs.stripe.com/cli/listen), a seconda dell’ambito e del tipo di evento:

   #### Inoltrare gli eventi salienti

   Utilizza il seguente comando per inoltrare [eventi salienti](https://docs.stripe.com/event-destinations.md#events-overview) dal tuo account al tuo listener locale.

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

   #### Inoltrare eventi leggeri

   Utilizza il seguente comando per inoltrare [eventi leggeri](https://docs.stripe.com/event-destinations.md#events-overview) dal tuo account al tuo listener locale.

   ```bash
   stripe listen --forward-thin-to localhost:4242/webhook --thin-events "*"
   ```

   Questo comando presuppone che tu disponga di un sito web localhost sulla porta 4242 con un endpoint `POST /webhook`, che puoi configurare quando [crei un gestore](https://docs.stripe.com/webhooks.md#webhook-endpoint-def).

4. Il comando `stripe listen` restituisce il valore `{{WEBHOOK_SIGNING_SECRET}}`. Copia questo valore da utilizzare quando [crei un gestore](https://docs.stripe.com/webhooks.md#webhook-endpoint-def).

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

> Per utilizzare l’argomento `--forward-to` con `stripe listen`, devi eseguire il comando con la [CLI di Stripe](https://docs.stripe.com/cli.md) in un terminale. Questo comando non può essere eseguito nella [Workbench Shell](https://docs.stripe.com/workbench/shell.md) perché non supporta l’argomento `--forward-to`.

## Crea un gestore

Configura una funzione endpoint HTTP o HTTPS in grado di accettare richieste webhook con un metodo POST. Se stai ancora sviluppando la tua funzione endpoint su dispositivi locali, questa può utilizzare il protocollo HTTP. Quando sarà accessibile pubblicamente, la funzione endpoint del webhook deve utilizzare il protocollo HTTPS.

Utilizza la documentazione di riferimento dell’API Stripe per identificare gli [oggetti evento leggero](https://docs.stripe.com/api/v2/core/events/event-types.md) o gli [oggetti evento saliente](https://docs.stripe.com/api/events/types.md) che il tuo gestore di webhook deve elaborare.

Configura la funzione dell’endpoint in modo che:

- Gestisce le richieste POST con un payload JSON che include informazioni sull’evento.
- Verifica che la richiesta webhook sia stata generata da Stripe utilizzando il payload JSON, l’intestazione `Stripe-Signature` e il segreto di firma del webhook `whsec_` del passaggio precedente. Se la verifica non riesce, viene restituito un errore.
- Restituisce rapidamente un codice di stato positivo (`2xx`) prima di qualsiasi logica complessa che potrebbe causare un timeout. Ad esempio, devi restituire una risposta `200` prima di aggiornare una fattura di un cliente come pagata nel tuo sistema contabile.

> #### Non modificare il corpo non elaborato della richiesta
> 
> Stripe richiede il corpo raw della richiesta per eseguire la verifica della firma. Se stai utilizzando un framework, assicurati che non manipoli il corpo raw. Qualsiasi manipolazione del corpo raw della richiesta causa la non riuscita della verifica.
> 
> Scopri come [risolvere gli errori di verifica della firma](https://docs.stripe.com/webhooks/signature.md).

#### Endpoint di esempio

Questo frammento di codice è una funzione webhook configurata per verificare la presenza di eventi ricevuti da un account Stripe, gestire gli eventi e restituire risposte `200`. Fai riferimento al gestore eventi [salienti](https://docs.stripe.com/event-destinations.md#events-overview) quando utilizzi le risorse dell’API v1 e fai riferimento al gestore eventi [leggeri](https://docs.stripe.com/event-destinations.md#events-overview) quando utilizzi le risorse dell’API v2.

#### Gestore eventi salienti

Quando crei un gestore eventi salienti, utilizza la definizione dell’oggetto API impostata al momento dell’evento per la tua logica accedendo ai campi `data.object` dell’evento. È inoltre possibile recuperare la risorsa API dall’API Stripe per accedere alla definizione di oggetto più recente e aggiornata.

#### Ruby

```ruby
require 'json'
require 'stripe'

client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY'))

# Replace this endpoint secret with your unique endpoint secret key
# If you're testing with the CLI, run 'stripe listen' to find the secret key
# If you defined your endpoint using the API or the Dashboard, check your webhook settings for your endpoint secret: https://dashboard.stripe.com/webhooks
endpoint_secret = 'whsec_...';

# 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

  # Check that you have configured webhook signing
  if endpoint_secret
    # Retrieve the event by verifying the signature using the raw body and the endpoint secret
    signature = request.env['HTTP_STRIPE_SIGNATURE'];
    begin
      event = Stripe::Webhook.construct_event(
        payload, signature, endpoint_secret
      )
    rescue Stripe::SignatureVerificationError => e
      puts "⚠️  Webhook signature verification failed. #{e.message}"
      status 400
    end
  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
```

#### Gestore eventi leggeri (Clover+)

Quando crei un gestore eventi leggeri, utilizza il metodo `fetchRelatedObject()` per recuperare l’ultima versione dell’oggetto associato all’evento. Gli eventi potrebbero contenere [dati aggiuntivi](https://docs.stripe.com/event-destinations.md#fetch-data) che puoi recuperare solo tramite il metodo di istanza `.fetchEvent()` su `EventNotification`. La forma esatta di tali dati dipende dal `type` di evento.

I tipi di evento devono essere disponibili al momento del rilascio per generare classi nella versione dell’SDK. Per gestire gli eventi per cui l’SDK non dispone di classi, utilizza la classe `UnknownEventNotification`.

#### Python

```python
import os
from stripe import StripeClient
from stripe.events import UnknownEventNotification

from flask import Flask, request, jsonify

app = Flask(__name__)
api_key = os.environ.get("STRIPE_API_KEY", "")
webhook_secret = os.environ.get("WEBHOOK_SECRET", "")

client = StripeClient(api_key)

@app.route("/webhook", methods=["POST"])
def webhook():
    webhook_body = request.data
    sig_header = request.headers.get("Stripe-Signature")

    try:
        event_notif = client.parse_event_notification(
            webhook_body, sig_header, webhook_secret
        )

        # type checkers will narrow the type based on the `type` property
        if event_notif.type == "v1.billing.meter.error_report_triggered":
            # in this block, event_notification is typed as
            # a V1BillingMeterErrorReportTriggeredEventNotification

            # there's basic info about the related object in the notification
            print(f"Meter w/ id {event_notif.related_object.id} had a problem")

            # or you can fetch the full object form the API for more details
            meter = event_notif.fetch_related_object()
            print(
                f"Meter {meter.display_name} ({meter.id}) had a problem"
            )

            # And you can always fetch the full event:
            event = event_notif.fetch_event()
            print(f"More info: {event.data.developer_message_summary}")

        elif event_notif.type == "v1.billing.meter.no_meter_found":
            # in this block, event_notification is typed as
            # a V1BillingMeterNoMeterFoundEventNotification

            # that class doesn't define `fetch_related_object` because the event
            # has no related object.
            # so this line would correctly give a type error:
            # meter = event_notif.fetch_related_object()

            # but fetching the event always works:
            event = event_notif.fetch_event()
            print(
                f"Err! No meter found: {event.data.developer_message_summary}"
            )

        # Events that were introduced after this SDK version release are
        # represented as `UnknownEventNotification`s.
        # They're valid, the SDK just doesn't have corresponding classes for them.
        # You must match on the "type" property instead.
        elif isinstance(event_notif, UnknownEventNotification):
            # these lines are optional, but will give you more accurate typing in this block
            from typing import cast

            event_notif = cast(UnknownEventNotification, event_notif)

            # continue matching on the type property
            # from this point on, the `related_object` property _may_ be None
            # (depending on the event type)
            if event_notif.type == "some.new.event":
                # if this event type has a related object, you can fetch it
                obj = event_notif.fetch_related_object()
                # otherwise, `obj` will just be `None`
                print(f"Related object: {obj}")

                # you can still fetch the full event, but it will be untyped
                event = event_notif.fetch_event()
                print(f"New event: {event.data}")  # type: ignore

        return jsonify(success=True), 200
    except Exception as e:
        return jsonify(error=str(e)), 400
```

## Testa il gestore

Prima di attivare il servizio della funzione del tuo endpoint webhook, consigliamo di testare l’integrazione della tua applicazione attivando eventi in una sandbox o inviando eventi di test con la [CLI di Stripe](https://docs.stripe.com/cli.md).

### Attiva eventi di prova

Per inviare eventi di test, attiva un tipo di evento sottoscritto dalla destinazione dell’evento creando manualmente un oggetto nella Dashboard Stripe. Scopri come attivare gli eventi con [Stripe for Visual Studio Code](https://docs.stripe.com/stripe-vscode.md).

#### Attivare un evento saliente

Puoi utilizzare il seguente comando nella [Shell di Stripe](https://docs.stripe.com/workbench/shell.md) o nella [CLI di Stripe](https://docs.stripe.com/cli.md). Questo esempio attiva un evento `payment_intent.succeeded`:

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

#### Attivare un evento leggero

Puoi utilizzare il seguente comando nella [CLI di Stripe](https://docs.stripe.com/cli.md). Questo esempio attiva un evento `v1.billing.meter.error_report_triggered`:

```bash
stripe trigger v1.billing.meter.error_report_triggered
Setting up fixture for: list_billing_meters
Running fixture for: list_billing_meters
Setting up fixture for: billing_meter
Running fixture for: billing_meter
Setting up fixture for: list_billing_meters_after_creation
Running fixture for: list_billing_meters_after_creation
Setting up fixture for: billing_meter_event_session
Running fixture for: billing_meter_event_session
Setting up fixture for: create_billing_meter_event_stream
Running fixture for: create_billing_meter_event_stream
Trigger succeeded! Check dashboard for event details.
```

## Optional: Crea una destinazione di eventi per Connect

Quando [crei una destinazione di eventi](https://docs.stripe.com/webhooks.md#create-webhook-endpoint) come piattaforma Connect, scegli quale ambito deve intercettare:

#### Dashboard

- **Il tuo account**: eventi provenienti dalle risorse nel tuo account.
- **Account connessi**: eventi provenienti dalle risorse appartenenti ai tuoi account connessi.

#### API

- [events_from=[“@self”]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from): eventi provenienti dalle risorse nel tuo account.
- [events_from=[“@accounts”]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from): eventi provenienti dalle risorse appartenenti ai tuoi account connessi.

Registra una destinazione di eventi per **Account connessi** per ricevere eventi provenienti dalle risorse appartenenti ai tuoi account connessi. Tra gli esempi rientrano [addebiti diretti](https://docs.stripe.com/connect/direct-charges.md), clienti e metodi di pagamento degli account connessi, errori dei payout e aggiornamenti legacy relativi agli eventi salienti del ciclo di vita degli account connessi, come attivazione, verifica, modifiche agli account esterni e disconnessioni degli account. Per Accounts v2, questo ambito riceve solo eventi salienti per gli oggetti Account che rappresentano i tuoi account connessi.

A seconda dell’integrazione Connect, potrebbe essere necessario registrare una destinazione di eventi anche per **Il tuo account**. I motivi includono:

- L’elaborazione di eventi provenienti dalle risorse nel tuo account della piattaforma, inclusi clienti della piattaforma, addebiti di proprietà della piattaforma, [pagamenti al destinatario](https://docs.stripe.com/connect/destination-charges.md) e [pagamenti e trasferimenti separati](https://docs.stripe.com/connect/separate-charges-and-transfers.md).
- L’elaborazione di eventi leggeri relativi agli oggetti Accounts v2 che rappresentano account connessi.

Per maggiori dettagli, consulta i [webhook Connect](https://docs.stripe.com/connect/webhooks.md?accounts-namespace=v2).

### Esegui test su Connect in locale senza un URL registrato

#### Eventi istantanei

Utilizza il seguente comando per inoltrare [eventi salienti](https://docs.stripe.com/event-destinations.md#events-overview) dagli account connessi al tuo listener locale.

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

#### Eventi thin

Utilizza il seguente comando per inoltrare [eventi leggeri](https://docs.stripe.com/event-destinations.md#events-overview) dagli account connessi al tuo listener locale.

```bash
stripe listen --forward-thin-connect-to localhost:4242/webhook --thin-events "*"
```

## Optional: Crea una destinazione di eventi per Organizations

Quando [crei una destinazione di eventi](https://docs.stripe.com/webhooks.md#create-webhook-endpoint) come Organization, scegli quale ambito deve intercettare:

#### Dashboard

- **Account nella tua organizzazione**: eventi provenienti dalle risorse all’interno degli account connessi della tua organizzazione.
- **Account connessi**: eventi provenienti da risorse all’interno degli account connessi della tua organizzazione.

#### API

- [events_from=[“@organization_members”]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from): eventi provenienti da risorse negli account della tua organizzazione.
- [events_from=[“@organization_members/@accounts”]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from): eventi provenienti dalle risorse all’interno degli account connessi della tua organizzazione.

### 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, ma per alcuni tipi di evento attende una risposta. In questi casi, Stripe si comporta in modo diverso a seconda che la destinazione di eventi risponda o meno.

Se la destinazione dell’evento riceve eventi dell’[Organizzazione](https://docs.stripe.com/get-started/account/orgs.md), quelli che richiedono una risposta hanno le seguenti limitazioni:

- 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](https://docs.stripe.com/webhooks.md#example-endpoint) in un account Stripe all’interno dell’organizzazione. Usa `issuing_authorization.request` per autorizzare le richieste di acquisto in tempo reale.
- Le organizzazioni che ricevono `checkout_sessions.completed` non sono in grado di [gestire il comportamento di reindirizzamento](https://docs.stripe.com/checkout/fulfillment.md#redirect-hosted-checkout) quando si incorpora [Checkout](https://docs.stripe.com/payments/checkout.md) direttamente nel proprio sito web o si reindirizzano i clienti a una pagina di pagamento in hosting su Stripe. Per influenzare il comportamento di reindirizzamento di Checkout, elaborare questo tipo di evento con un [endpoint webhook](https://docs.stripe.com/webhooks.md#example-endpoint) configurato in un account Stripe all’interno dell’organizzazione.
- Le organizzazioni di destinazione che rispondono senza successo a un evento `invoice.created` non possono influire sulla [finalizzazione automatica delle fatture quando si utilizza la riscossione automatica](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand). È necessario elaborare questo tipo di evento con un [endpoint webhook](https://docs.stripe.com/webhooks.md#example-endpoint) configurato in un account Stripe all’interno dell’organizzazione per attivare la finalizzazione automatica delle fatture.

#### Usa `context`

#### Eventi istantanei

Questo frammento di codice è una funzione webhook configurata per verificare la presenza di eventi ricevuti, rilevare l’account di origine, se applicabile, gestire l’evento e restituire una risposta `200`.

#### Ruby

```ruby
require 'json'

client = Stripe::StripeClient.new('sk_...')

# 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 = client.v1.customers.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 = client.v1.payment_methods.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
```

#### Gestore eventi leggeri (Clover+)

Utilizza la proprietà `context` di `EventNotification` per identificare l’account per eventi all’interno della tua [organizzazione](https://docs.stripe.com/get-started/account/orgs.md). Devi impostare manualmente [l’intestazione Stripe-Context](https://docs.stripe.com/context.md) per tutte le chiamate API a eccezione di `.fetchRelatedObject()` and `.fetchEvent()`, che lo fanno automaticamente.

#### Python

```python
org_api_key = os.environ.get("STRIPE_API_KEY")
webhook_secret = os.environ.get("WEBHOOK_SECRET")
client = StripeClient(org_api_key)

# inside your webhook handler
event_notification = client.parse_event_notification(payload, sig_header, webhook_secret)

# uses `context` automatically
event_notification.fetch_event()

# pass context manually for other API requests
client.v1.invoices.list(stripe_context=event_notification.context)
```

## 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, apri [Workbench](https://docs.stripe.com/workbench.md), seleziona l’endpoint del webhook in **Webhook**, quindi seleziona la scheda **Eventi**. La scheda **Eventi** fornisce un elenco di eventi e indica se sono `Delivered`, `Pending`, o `Failed`. Fai clic su un evento per visualizzare i metadati, tra cui il codice di stato HTTP del tentativo di consegna e l’ora delle consegne future in sospeso.

Puoi anche usare la [CLI di Stripe](https://docs.stripe.com/cli.md) per [ascoltare gli eventi](https://docs.stripe.com/webhooks.md#test-webhook) direttamente nel tuo terminale.

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

| Stato webhook in sospeso | Descrizione | Correggi |
| --- | --- | --- |
| (Connessione impossibile) ERR | Non siamo in grado di stabilire una connessione con il server di destinazione. | Assicurati che il tuo dominio host sia accessibile pubblicamente su Internet. |
| ERR (`302` o altro stato `3xx`) | Il server di destinazione ha tentato di reindirizzare la richiesta a un’altra posizione. Le risposte di reindirizzamento alle richieste di webhook sono considerate errori. | Imposta la destinazione dell’endpoint del webhook sull’URL risolto dal reindirizzamento. |
| ERR (`400` o altro stato `4xx`) | Il server di destinazione non elabora la richiesta o non è in grado di farlo. Ciò può verificarsi quando il server rileva un errore (`400`), quando l’URL di destinazione ha restrizioni di accesso (`401`, `403`, `405`), o quando l’URL di destinazione non esiste (`404`). | Assicurati che l’endpoint sia pubblicamente accessibile a Internet e accetta un metodo HTTP POST. |
| ERR (`500` o altro stato `5xx`) | Il server di destinazione ha rilevato un errore durante l’elaborazione della richiesta. | Esamina i registri della tua applicazione per capire perché restituisce un errore `500`. |
| (errore TLS) ERR | Non è stato possibile stabilire una connessione con il server di destinazione. I problemi con il certificato SSL/TLS o un certificato intermedio nella catena di certificati del server di destinazione di solito causano questi errori. Stripe richiede *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) `v1.2` o versione superiore. | Esegui un [test del server SSL](https://www.ssllabs.com/ssltest/) per individuare i problemi che potrebbero aver causato l’errore. |
| (Tempo scaduto) ERR | Il server di destinazione ha impiegato troppo tempo per rispondere alla richiesta webhook. | Assicurati di rinviare la logica complessa e restituire immediatamente una risposta positiva nel codice di gestione del webhook. |

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

Sono disponibili due modi per riprovare a gestire manualmente gli eventi:

- Nella Dashboard di Stripe, fai clic su **Invia di nuovo** per un evento specifico. Funziona fino a 15 giorni dopo la creazione dell’evento.
- Con la [CLI di Stripe](https://docs.stripe.com/cli/events/resend), esegui il comando `stripe events resend <event_id> --webhook-endpoint=<endpoint_id>`. Funziona fino a 30 giorni dopo la creazione dell’evento.

Il reinvio manuale di un evento che in precedenza non era stato consegnato a un endpoint webhook non annulla il [comportamento di ripetizione automatica delle operazioni non riuscite](https://docs.stripe.com/webhooks.md#automatic-retries) di Stripe, anche se genera un codice di stato `2xx`. Scopri come [elaborare gli eventi webhook non consegnati](https://docs.stripe.com/webhooks/process-undelivered-events.md) per interrompere la ripetizione futura delle operazioni non riuscite.

### 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 tua destinazione degli eventi non dipenda dalla ricezione degli eventi in un ordine specifico. Gli eventi salienti registrano l’evento `created` in secondi, per cui eventi distinti possono condividere un timestamp. Non usare `created` per determinare l’ordine degli eventi o per verificare se un evento è già stato elaborato. Tieni traccia degli [ID evento](https://docs.stripe.com/api/events/object.md#event_object-id) per identificare consegne duplicate. Puoi anche usare l’API per recuperare gli oggetti mancanti. Ad esempio, se ricevi per primo l’evento `invoice.paid`, puoi recuperare gli oggetti fattura, addebito e abbonamento tramite le relative informazioni.

### Controllo delle versioni dell’API

Quando si verifica l’evento, la versione dell’API nelle impostazioni dell’account determina la versione dell’API e quindi la struttura di un [evento](https://docs.stripe.com/api/events.md) inviato alla destinazione. Ad esempio, se il tuo account è impostato su una versione precedente dell’API, come la 2015-02-16, e modifichi la versione dell’API per una richiesta specifica con [controllo delle versioni](https://docs.stripe.com/api.md#versioning), l’oggetto [Event](https://docs.stripe.com/api/events.md) generato e inviato alla destinazione è ancora basato sulla versione dell’API 2015-02-16. Una volta creati, gli oggetti [Event](https://docs.stripe.com/api/events.md) non possono più essere modificati. Ad esempio, se aggiorni un addebito, quello originale rimane invariato. Di conseguenza, gli aggiornamenti successivi della versione dell’API dell’account non modificano in modo retroattivo gli oggetti [Event](https://docs.stripe.com/api/events.md) esistenti. Anche il recupero di un [Event](https://docs.stripe.com/api/events.md) precedente chiamando `/v1/events` con una versione più recente dell’API non influisce sulla struttura dell’evento ricevuto. Puoi impostare le destinazioni degli eventi di test sulla versione predefinita dell’API o su quella più recente dell’API. L’oggetto [Event](https://docs.stripe.com/api/events.md) inviato alla destinazione è strutturato per la versione specificata della destinazione dell’evento.

## 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](https://docs.stripe.com/api/events/object.md#event_object-id) 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](https://docs.stripe.com/api/webhook_endpoints/update.md#update_webhook_endpoint-enabled_events) 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](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_\(CSRF\)). 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.

#### Rails

```ruby
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* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol).

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

Il segreto utilizzato per verificare che gli eventi provengano da Stripe può essere modificato nella scheda [Webhook](https://dashboard.stripe.com/webhooks) in Workbench. Per mantenerlo al sicuro, ti consigliamo di ruotare (modificare) periodicamente i segreti oppure di farlo quando sospetti che un segreto sia stato compromesso.

Per generare una chiave:

1. Fai clic su ciascun endpoint nella scheda [Webhook](https://dashboard.stripe.com/webhooks) di Workbench per il quale desideri ruotare il segreto.
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

Senza verifica, un malintenzionato potrebbe inviare eventi webhook falsi al tuo endpoint per attivare azioni quali l’evasione di ordini, la concessione dell’accesso all’account o la modifica dei registri. Verifica sempre che gli eventi webhook provengano da Stripe prima di agire su di essi.

Utilizza entrambe le protezioni:

- **Elenco IP consentiti**: Stripe invia eventi webhook da un elenco predefinito di [indirizzi IP](https://docs.stripe.com/ips.md). Configura il tuo server o firewall in modo che accetti solo richieste webhook provenienti da questi indirizzi.
- **Verifica della firma**: Stripe firma ogni evento webhook includendo una firma nell’header `Stripe-Signature`. Verifica la firma utilizzando le nostre [librerie ufficiali](https://docs.stripe.com/webhooks.md#verify-signature) oppure segui i [passaggi per la verifica manuale](https://docs.stripe.com/webhooks.md?verify=verify-manually#verify-signature) per assicurarti che l’evento non sia stato inviato o modificato da terze parti.

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](https://dashboard.stripe.com/webhooks) per visualizzare tutti i tuoi endpoint. Seleziona un endpoint di cui desideri visualizzare il segreto, quindi fai clic su **Fai clic per mostrare**.

Stripe genera una chiave privata unica per ogni endpoint. Se utilizzi lo stesso endpoint per le [chiavi API di test e live](https://docs.stripe.com/keys.md#test-live-modes), 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.

#### Verifica la firma

#### Verifica con le librerie ufficiali (opzione consigliata)

### Verifica le firme del webhook con le librerie ufficiali

Per verificare le firme, ti consigliamo di utilizzare le nostre librerie ufficiali. Per eseguire la verifica, specifica il paylod dell’evento, l’intestazione `Stripe-Signature` e la chiave privata dell’endpoint. Se la verifica non va a buon fine, sarà visualizzato un messaggio di errore.

Se ricevi un errore di verifica della firma, consulta la nostra guida sulla [risoluzione dei problemi](https://docs.stripe.com/webhooks/signature.md).

> Stripe richiede il corpo raw della richiesta per eseguire la verifica della firma. Se stai utilizzando un framework, assicurati che non manipoli il corpo raw. Qualsiasi manipolazione del corpo raw della richiesta causa la non riuscita della verifica.

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

#### Verifica manuale

### Verifica manualmente le firme dei webhook

Anche se è consigliabile utilizzare le nostre librerie ufficiali per verificare le firme degli eventi webhook, puoi creare una soluzione personalizzata seguendo questa procedura.

L’intestazione `Stripe-Signature` inclusa in ogni evento firmato contiene un timestamp e una o più firme che devi verificare. Il timestamp ha un prefisso `t=` e ogni firma ha un prefisso *scheme*. Gli schemi sono identificati da una `v` iniziale e un numero intero successivo. Attualmente, l’unico schema valido per le firme live è `v1`. Per facilitare i test, Stripe invia una firma aggiuntiva con uno schema `v0` fittizio per gli eventi di test.

```
Stripe-Signature:
t=1492774577,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,
v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39
```

> Forniamo degli a capo per maggiore chiarezza, ma una vera intestazione `Stripe-Signature` è composta da un’unica riga.

Stripe genera le firme utilizzando una modalità di autenticazione dei messaggi basata su hash ([HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)) con [SHA-256](https://en.wikipedia.org/wiki/SHA-2). Per impedire gli [attacchi basati su download](https://en.wikipedia.org/wiki/Downgrade_attack), ignora tutti gli schemi diversi da `v1`.

Puoi avere più firme con la stessa coppia schema-chiave privata quando [generi la chiave privata di un endpoint](https://docs.stripe.com/webhooks.md#roll-endpoint-secrets) e mantieni attiva la chiave privata precedente per massimo 24 ore. Durante questo periodo di tempo, l’endpoint ha più chiavi private attive e Stripe genera una firma per ognuna di esse.

Per creare una soluzione manuale per la verifica delle firme, è necessario completare i seguenti passaggi:

#### Fase 1: estrai il timestamp e le firme dall’intestazione

Per ottenere un elenco degli elementi, suddividi l’intestazione, utilizzando il carattere `,` come separatore. Poi suddividi ogni elemento, utilizzando il carattere `=` come separatore, per ottenere un prefisso e una coppia di valori.

Il valore del prefisso `t` corrisponde al timestamp e `v1` corrisponde alla firma (o alle firme). Puoi ignorare tutti gli altri elementi.

#### Fase 2: prepara la stringa `signed_payload`

La stringa `signed_payload` viene creata concatenando:

- Il timestamp (come stringa)
- Il carattere `.`
- Il payload JSON effettivo, ovvero il corpo della richiesta

#### Fase 3: determina la firma prevista

Calcola un HMAC con la funzione hash SHA256. Utilizza la chiave privata di firma dell’endpoint come chiave e la stringa `signed_payload` come messaggio.

#### Fase 4: confronta le firme

Confronta la firma (o le firme) nell’intestazione con la firma prevista. Per una corrispondenza di eguaglianza, calcola la differenza tra il timestamp corrente e quello ricevuto, poi decidi se la differenza rientra nella tolleranza.

Per proteggerti dagli attacchi temporizzati, utilizza un confronto di stringhe a tempo costante per confrontare la firma prevista con ogni firma ricevuta.

### Impedire gli attacchi di tipo replay

Un [attacco di tipo replay](https://en.wikipedia.org/wiki/Replay_attack) 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](https://en.wikipedia.org/wiki/Network_Time_Protocol)) per garantire che l’orologio del server sia preciso e sincronizzato con l’ora dei server di Stripe.

> Non utilizzare un valore di tolleranza `0`. L’utilizzo di un valore di tolleranza `0` disabilita completamente il controllo di frequenza.

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

Il tuo [endpoint](https://docs.stripe.com/webhooks.md#example-endpoint) deve restituire rapidamente un codice di stato positivo (`2xx`) prima di eseguire qualsiasi logica complessa che potrebbe causare un timeout. Ad esempio, devi restituire una risposta `200` prima di aggiornare una fattura di un cliente come pagata nel tuo sistema contabile.

## See also

- [Inviare eventi ad Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md)
- [Invia eventi alla Griglia di eventi di Azure](https://docs.stripe.com/event-destinations/eventgrid.md)
- [Elenco dei tipi di evento leggero](https://docs.stripe.com/api/v2/core/events/event-types.md)
- [Elenco dei tipi di eventi salienti](https://docs.stripe.com/api/events/.md)
- [Strumento interattivo per la creazione di endpoint del webhook](https://docs.stripe.com/webhooks/quickstart.md)