Passa al contenuto principale

Configurazione webhook Stripe

Se hai collegato Stripe usando Connect with Stripe, questa pagina ti guida nell'unico passaggio manuale richiesto da Stripe in seguito: creare tu stesso un endpoint webhook nella tua Dashboard Stripe, schermata per schermata.

Prima di iniziare​

  • Questo vale solo per Connect with Stripe. Se hai collegato Stripe inserendo tu stesso la tua Chiave segreta e Chiave pubblica (vedi Pagamenti — Collegare Stripe), Agon registra il webhook automaticamente e non ti serve questa pagina.
  • Perché devi farlo tu: Stripe non permette a un account collegato tramite OAuth ("Connect") di registrare automaticamente endpoint webhook — è una restrizione lato Stripe, non un limite di Agon. Devi farlo una sola volta.
  • Tieni pronto l'URL webhook del tuo studio. Lo trovi in Agon sotto Impostazioni → Fatturazione, ed è simile a https://studio-<id-del-tuo-studio>.agon-studio.dev/api/billing/webhook — unico per il tuo studio. Tieni quella pagina aperta in un'altra finestra o scheda per poterlo copiare al passaggio 7.

Passaggi​

  1. Apri la tua Dashboard Stripe e vai su Developers → Webhooks — oppure direttamente su Workbench → Webhooks.

  2. Clicca Add destination.

    Pagina Webhooks di Stripe Workbench con il pulsante Add destination

  3. Stripe apre una procedura guidata Create an event destination in tre passaggi: Select events → Choose destination type → Configure your destination.

  4. In Select events, sotto Event destination scope scegli Your account — non Connected accounts, che serve solo alle piattaforme che ricevono eventi dagli account Stripe di altre persone. Il tuo studio è questo account. Sotto Payload style, lascia selezionato Snapshot — non Thin; Agon ha bisogno dell'intero oggetto evento, non solo di un id da recuperare in seguito. Lascia API version sul valore proposto di default da Stripe.

    Configure your event destination: selezionati Your account e Snapshot

  5. Sempre in Select events, usa il campo di ricerca Find event by name or description… — molto più rapido che scorrere l'intero elenco per categorie — e seleziona esattamente questi 6 eventi, uno alla volta:

    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.paid
    • invoice.payment_failed

    Campo di ricerca eventi: Find event by name or description

    Una volta selezionati tutti e 6, clicca Continue.

  6. In Choose destination type, seleziona Webhook endpoint — la prima opzione. Le altre due, Amazon EventBridge e Azure Event Grid, servono per instradare eventi verso la tua infrastruttura cloud e non si applicano qui. Clicca Continue.

    Choose destination type con Webhook endpoint selezionato

  7. In Configure your destination, Stripe mostra un riepilogo delle tue scelte (Events from: Your account, Payload style: Snapshot, Listening to: 6 events), seguito da tre campi:

    • Destination name — facoltativo, va bene qualsiasi nome (per esempio "Agon"). Serve solo come riferimento nella tua Dashboard Stripe e non ha alcun effetto funzionale.
    • Endpoint URL — incolla qui l'URL webhook del tuo studio preso dalla pagina Impostazioni → Fatturazione di Agon, esattamente come mostrato. Non digitarlo a mano — un solo errore di battitura impedisce per sempre a Stripe di raggiungere il tuo studio.
    • Description — facoltativo, puoi lasciarlo vuoto.

    Clicca il pulsante per creare la destinazione.

    Configure destination con i campi Destination name, Endpoint URL e Description

  8. Stripe mostra ora un Signing secret per la nuova destinazione, a volte dietro un controllo "reveal" da cliccare prima. Copialo.

  9. In Agon, vai su Impostazioni → Fatturazione e incollalo nel campo Segreto webhook — lo stesso campo descritto in Pagamenti — Collegare Stripe, sempre visibile in quella pagina e non nascosto dietro un'opzione aggiuntiva. Clicca Salva.

Cosa fare se qualcosa va storto?​

Non sono sicuro se scegliere "Your account" o "Connected accounts"

Scegli Your account. Il tuo studio è l'account Stripe che stai configurando — Connected accounts si applica solo se fossi una piattaforma che riceve eventi dagli account Stripe separati di altre persone, il che non è il tuo caso.

I miei pagamenti risultano ancora In sospeso dopo questa configurazione

Verifica che l'Endpoint URL sia stato incollato esattamente, senza caratteri in più o segmenti mancanti, e che il Segreto webhook salvato in Impostazioni → Fatturazione corrisponda al signing secret mostrato da Stripe per questa specifica destinazione. Vedi anche Pagamenti — Cosa fare se qualcosa va storto?.

Devo aggiungere un evento in seguito o cambiare l'URL

Riapri la destinazione da Workbench → Webhooks nella tua Dashboard Stripe e modificala lì. Devi aggiornare qualcosa in Agon solo se cambia anche il signing secret.

Pagine correlate​