Skip to main content
Webhook Cover Image
Webhooks deliver real-time notifications when events occur in your Dodo Payments account. Use them to automate workflows, update your database, send notifications, and keep your systems in sync.
Dodo Payments webhooks follow the Standard Webhooks specification for signature verification and payload structure.

Key Features

Webhooks provide real-time delivery with built-in security, automatic retries, and event filtering. All official SDKs include signature verification helpers, and the dashboard offers testing, monitoring, and replay tools.

Getting Started

1

Go to Developer → Webhooks

In the Dodo Payments Dashboard, navigate to Developer → Webhooks.
2

Click Add Endpoint

Click Add endpoint to create a new webhook receiver.
3

Enter Your Endpoint URL

Provide the HTTPS URL where Dodo Payments will send webhook events, or select an integration connector (Slack, Discord, Zapier, Resend, etc.) to route events to a third-party service without writing code.
4

Select Events

Choose which events to receive. Events are organized by resource (payment, subscription, dispute, etc.). You can select individual events or an entire resource to receive all related events.
5

Save

Click Create endpoint. Your webhook signing secret appears on the endpoint’s Overview tab.
Keep your webhook secret secure. Never expose it in client-side code or version control.
To rotate your webhook secret, open the endpoint and click Rotate secret next to the secret on the Overview tab. The old secret remains valid for 24 hours after rotation.

Integration Connectors

Route webhook events directly to third-party services using integration connectors, eliminating the need to build and maintain custom webhook handlers.

How Connectors Work

A connector transforms Dodo Payments events into the format the destination expects. Which details you provide depends on the destination: The dashboard shows all connectors available to your business. See External Integrations for what each destination can do with the events.

Setting Up a Connector

When creating or editing an endpoint, select a connector and the side sheet shows setup instructions for that destination. Test the transformation before saving to confirm events are converted correctly.
Use a connector to reach a supported destination without writing code. If you need custom logic, use a standard endpoint with a transformation instead.

Configuring Subscribed Events

Configure which events each webhook endpoint receives.
1

Navigate to Webhook Endpoints

Go to Developer → Webhooks and click on your endpoint.
2

Open Event Configuration

Click Edit to open the endpoint configuration side sheet.
3

Select Events

The event type selector displays all available webhook events organized in a searchable tree, grouped by resource (e.g., payment, subscription, dispute). Check the boxes next to the events you want to receive. You can select individual events, an entire resource, or mix and match.
4

Save Configuration

Click Save to apply your changes.
If you deselect all events, your webhook endpoint receives every event type. Select only the events your application needs.

Event Catalog

Go to Developer → Webhooks and open the Event catalog tab to see every event type Dodo Payments can send. Select an event to view its schema and sample payload.

Webhook Events Guide

Browse events as reference documentation, grouped by resource.

Webhook Delivery

Timeouts

I webhook hanno un timeout di 30 secondi sia per le operazioni di connessione sia per quelle di lettura. Elabora i webhook in modo asincrono restituendo immediatamente un codice di stato 200, quindi gestisci l’evento in background.

Retry automatici

Le consegne non riuscite vengono ritentate con un backoff esponenziale, per un massimo di 8 tentativi totali: Usa il dashboard per riprodurre manualmente i messaggi non riusciti o recuperare in blocco i messaggi di un intervallo di tempo specifico.

Idempotenza

Ogni webhook include un header webhook-id univoco. Memorizza questo ID per rilevare e ignorare gli eventi duplicati, poiché i retry possono consegnare lo stesso evento più volte.
Implementa sempre i controlli di idempotenza. A causa dei retry, potresti ricevere lo stesso evento più volte.

Ordinamento degli eventi

Gli eventi possono arrivare fuori ordine a causa dei retry o delle condizioni di rete. Ogni webhook include un campo timestamp; usalo per ordinare gli eventi se la tua applicazione lo richiede. Ricevi sempre lo stato più recente del payload al momento della consegna.

Protezione dei webhook

Convalida sempre i payload dei webhook e usa HTTPS.

Verifica delle firme

Ogni webhook include un header webhook-signature: una firma HMAC SHA256 del payload e del timestamp, firmata con la tua secret key.

Verifica tramite SDK (consigliata)

Tutti gli SDK ufficiali includono helper integrati. Imposta DODO_PAYMENTS_WEBHOOK_KEY durante l’inizializzazione del client, quindi chiama unwrap() per verificare e analizzare il payload. Sono disponibili due metodi:
  • unwrap — Verifica la firma con la tua secret key del webhook, quindi analizza il payload.
  • unsafe_unwrap — Analizza il payload senza verificarlo. Usalo solo per i test.
I nomi dei metodi seguono le convenzioni di ogni linguaggio: unwrap / unsafeUnwrap in TypeScript, unwrap / unsafe_unwrap in Python e Unwrap / UnsafeUnwrap in Go.
Fornisci la secret key del webhook tramite DODO_PAYMENTS_WEBHOOK_KEY durante l’inizializzazione del client Dodo Payments.

Verifica manuale (alternativa)

Se non usi un SDK, verifica autonomamente la firma:
  1. Crea il contenuto firmato unendo webhook-id, webhook-timestamp e il corpo della richiesta non elaborato con dei punti: {id}.{timestamp}.{body}. Usa il corpo non elaborato esattamente come ricevuto, prima di qualsiasi analisi JSON.
  2. Prendi la tua secret key del webhook. Se inizia con whsec_, rimuovi quel prefisso, quindi decodifica in base64 il resto per ottenere la signing key.
  3. Calcola l’HMAC-SHA256 del contenuto firmato con la signing key e codifica il risultato in base64.
  4. L’header webhook-signature contiene una o più firme separate da spazi, ciascuna nel formato v1,<base64-signature>. La richiesta è valida se una qualsiasi firma v1 corrisponde alla tua. Confronta usando una funzione constant-time.
  5. Rifiuta la richiesta se webhook-timestamp è troppo distante dall’ora corrente, per prevenire gli attacchi di replay. Le librerie Standard Webhooks consentono 5 minuti.
Consulta le librerie Standard Webhooks per le implementazioni di riferimento. Per i formati dei payload degli eventi, consulta Webhook Payload.

Indirizzi IP di origine

La verifica della firma è il metodo di autenticazione supportato. Dimostra che la richiesta è stata firmata con la tua secret key del webhook, cosa che un controllo a livello di rete non può fare. Le consegne dei webhook provengono da un pool di indirizzi IP che cambia nel tempo. Non fare affidamento sulle allowlist IP per l’autenticazione. Verifica sempre invece l’header webhook-signature, come descritto in Verifica delle firme. Se il tuo firewall richiede un’allowlist:
  • Non codificare permanentemente gli indirizzi. Gli intervalli cambiano nel tempo e le regole obsolete bloccano silenziosamente le consegne.
  • Richiedi gli intervalli correnti a support@dodopayments.com prima di configurare restrizioni sul firewall.
  • Presta attenzione agli avvisi di modifica. Quando cambiano gli indirizzi di consegna, informiamo via email i merchant interessati: applica gli aggiornamenti prima della data indicata.
  • Mantieni abilitata la verifica delle firme indipendentemente dalle regole di rete aggiunte.
Sulle piattaforme serverless e di hosting gestito, il filtraggio degli IP in ingresso è spesso indisponibile o poco pratico. In questi ambienti, la verifica delle firme è il controllo corretto.
Una consegna bloccata viene considerata un errore e ritentata secondo la pianificazione descritta in Retry automatici. Se le regole del firewall hanno causato errori nelle consegne, puoi reinviarle dopo aver corretto le regole: consulta Riprodurre e recuperare i messaggi.

Rispondere ai webhook

Il tuo webhook handler deve restituire un 2xx status code per confermare la ricezione. Qualsiasi altra risposta viene considerata un errore e il webhook verrà ritentato.

Best practice

  • Usa solo HTTPS. Gli endpoint HTTP sono vulnerabili all’intercettazione.
  • Rispondi immediatamente. Restituisci subito un codice di stato 200, quindi elabora l’evento in modo asincrono.
  • Implementa l’idempotenza. Usa l’header webhook-id per rilevare e ignorare gli eventi duplicati.
  • Proteggi la tua secret key. Memorizza DODO_PAYMENTS_WEBHOOK_KEY nelle variabili d’ambiente o in un secrets manager, mai nel controllo versione.

Struttura del payload del webhook

Formato della richiesta

string
obbligatorio
Identificatore univoco per questo evento webhook. Usalo per i controlli di idempotenza.
string
obbligatorio
Firma HMAC SHA256 per verificare l’autenticità del webhook.
string
obbligatorio
Timestamp Unix, in secondi, relativo al momento di invio del webhook.

Corpo della richiesta

string
obbligatorio
Identificatore dell’attività Dodo Payments.
string
obbligatorio
Tipo di evento che ha attivato questo webhook (ad esempio, payment.succeeded, subscription.active).
string
obbligatorio
Timestamp formattato secondo ISO 8601 relativo al momento in cui si è verificato l’evento.
object
obbligatorio
Payload specifico dell’evento contenente informazioni dettagliate sull’evento.

Payload di esempio

Event Types

Sfoglia tutti i tipi di eventi webhook disponibili

Event Payloads

Visualizza gli schemi dettagliati dei payload per ogni evento

Handle Payment Failures

Reagisci a payment.failed e recupera i pagamenti rifiutati

Testare i webhook

Inviare un evento di esempio

Testa la tua integrazione webhook direttamente dal dashboard:
1

Navigate to Webhooks

Vai a Developer → Webhooks e fai clic sul tuo endpoint.
2

Open Testing Tab

Fai clic sulla scheda Testing.
3

Send Example

Seleziona un tipo di evento e fai clic su Send example. Il payload di esempio viene consegnato all’URL del tuo endpoint esattamente come un evento reale, con la stessa firma.
4

Check Your Endpoint

Conferma che l’evento sia arrivato, che la verifica della firma sia riuscita e che tu abbia restituito un codice di stato 2xx.
I messaggi non riusciti inviati dalla scheda Testing vengono ritentati secondo la normale pianificazione dei retry, come qualsiasi altro webhook.

Esempio di implementazione

Implementazione completa in Express.js con verifica e gestione dei webhook:
Testa accuratamente il tuo webhook handler usando l’interfaccia di testing del dashboard prima di elaborare gli eventi di produzione. In questo modo puoi individuare e correggere tempestivamente i problemi.

Testare i webhook con la CLI

La Dodo Payments CLI dispone di due comandi per testare i webhook durante lo sviluppo locale.

Ascoltare localmente i webhook in tempo reale

Inoltra gli eventi webhook reali dal tuo account in modalità di test al server di sviluppo locale:
La CLI apre una connessione WebSocket e inoltra ogni evento webhook al tuo endpoint locale (ad esempio, http://localhost:3000/webhook), mantenendo tutti gli header per testare la verifica delle firme.
Il listener funziona solo con API key in modalità di test. Esegui dodo login e seleziona prima Test Mode.

Attivare eventi webhook simulati

Invia payload webhook simulati a qualsiasi endpoint senza creare transazioni reali:
Questo strumento interattivo ti consente di scegliere un tipo di evento e invia un payload simulato realistico al tuo endpoint. Funziona in un ciclo, così puoi testare più eventi nella stessa sessione. Il comando trigger copre le famiglie di subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning ed entitlement grant. Non invia subscription.past_due o subscription.unpaused. Consulta Supported Webhook Events per l’elenco completo.
I payload webhook simulati da dodo wh trigger non sono firmati. Usa il metodo di analisi non verificato (unsafeUnwrap in TypeScript, unsafe_unwrap in Python, UnsafeUnwrap in Go) nel tuo webhook handler esclusivamente durante i test.

CLI Webhook Testing Docs

Consulta la documentazione completa sui test dei webhook con la CLI

Impostazioni avanzate

La scheda Advanced fornisce opzioni di configurazione aggiuntive per ottimizzare il comportamento del tuo endpoint webhook.

Limitazione della frequenza (throttling)

Controlla la frequenza con cui gli eventi webhook vengono consegnati al tuo endpoint. Per impostazione predefinita, ai webhook non viene applicato alcun limite di frequenza e gli eventi vengono consegnati non appena si verificano.
1

Open Advanced Tab

Dalla pagina dei dettagli dell’endpoint, fai clic sulla scheda Advanced.
2

Configure Rate Limit

Espandi la sezione Endpoint throttling.
3

Set Your Limit

Inserisci il numero massimo di messaggi al secondo, quindi fai clic su Save. Le consegne oltre questo limite vengono messe in coda anziché eliminate.

Header personalizzati

Aggiungi header HTTP personalizzati a tutte le richieste webhook inviate al tuo endpoint. Sono utili per l’autenticazione, il routing o l’aggiunta di metadati.
1

Add Headers

Nella sezione Custom headers, inserisci il nome e il valore di un header.
2

Add Multiple Headers

Fai clic su Add header per ogni header aggiuntivo, quindi fai clic su Save.

Trasformazioni

Le trasformazioni consentono di modificare il payload di un webhook e, facoltativamente, reindirizzarlo a un URL diverso. Usa le trasformazioni per:
  • Modificare la struttura del payload prima dell’elaborazione
  • Instradare i webhook verso endpoint diversi in base al contenuto
  • Aggiungere o rimuovere campi dal payload
  • Trasformare i formati dei dati
1

Enable Transformations

Nella sezione Transformation, attiva Enable transformation.
2

Configure Transformation

Scrivi le regole di trasformazione in JavaScript nell’editor del codice, quindi fai clic su Save. Il codice deve restituire l’oggetto webhook da handler().
3

Test Transformation

Usa l’interfaccia di test delle trasformazioni per verificare che la trasformazione funzioni correttamente prima della messa in produzione.
Le trasformazioni possono influire sulle prestazioni di consegna dei webhook. Esegui test approfonditi e mantieni la logica di trasformazione semplice ed efficiente.

Monitorare i log dei webhook

La scheda Logs fornisce visibilità sullo stato di consegna dei webhook.
1

Navigate to Logs Tab

Vai a Developer → Webhooks e apri la scheda Logs.
2

Browse Delivery History

Visualizza una tabella di tutti i tentativi di consegna dei webhook con colonne per Event type, Message ID, Event ID, Sent at, Attempted at, Response code e Duration.
3

Search and Filter

Usa la barra di ricerca per trovare messaggi specifici tramite ID o tipo di evento. Filtra per stato (Succeeded, Failed, Pending ecc.) per concentrarti sugli eventi da analizzare.
4

View Message Details

Fai clic su un messaggio qualsiasi per aprire la pagina dei dettagli del messaggio, che mostra:
  • Il payload webhook completo
  • Ogni tentativo di consegna con codice di risposta e durata
  • Il timestamp di ogni tentativo
  • Eventuali messaggi di errore provenienti dal tuo endpoint
Ogni tentativo include un’azione Replay per reinviare quel messaggio senza lasciare la pagina.

Monitoraggio delle attività

Vai a Developer → Webhooks e apri la scheda Activity per visualizzare le prestazioni di consegna tra i tuoi endpoint. Delivery activity rappresenta i tentativi nel tempo, raggruppati come Attempts per 5 minutes, Attempts per hour o Attempts per day in base all’intervallo. Ogni barra è suddivisa per risultato e, passando il mouse su un segmento, vengono mostrati lo stato, il numero di tentativi e la relativa quota sul totale. Per un endpoint, Delivery stats (last 24h) nella scheda Overview riepiloga le stesse informazioni per il giorno precedente.
La colonna Error rate (24h) nella scheda Endpoints mostra immediatamente quali endpoint richiedono attenzione.

Riprodurre e recuperare i messaggi

Il modo in cui reinvii un messaggio dipende dalla quantità di messaggi interessati:
  • Un messaggio — aprilo dalla scheda Logs e usa l’azione Replay sul tentativo.
  • Un intervallo di messaggi — apri l’endpoint, poiché le modalità in blocco agiscono su un solo endpoint alla volta.

Riprodurre in blocco

Apri l’endpoint da Developer → Webhooks. Sono disponibili tre modalità, ciascuna operativa esclusivamente su quell’endpoint:
1

Open More Actions

Sull’endpoint, apri More actions e scegli una delle tre modalità precedenti.
2

Set the Range

Compila l’intervallo richiesto dalla modalità, come indicato nella tabella.
3

Start the Run

Fai clic su Recover o Replay, in base alla modalità scelta.
Ogni esecuzione viene visualizzata in Replay history nella scheda Overview dell’endpoint, con la relativa modalità, l’intervallo di tempo, lo stato e il numero di messaggi reinviati.

Avvisi email

Il dashboard dei webhook non offre avvisi email per le consegne non riuscite. Per monitorare le consegne, vai a Developer → Webhooks e controlla le schede Logs e Activity.

Distribuire su piattaforme cloud

Guide specifiche per piattaforma per distribuire webhook handler sui principali provider cloud:

Vercel

Distribuire i webhook su Vercel con funzioni serverless

Cloudflare Workers

Eseguire i webhook sulla rete edge di Cloudflare

Supabase Edge Functions

Integrare i webhook con Supabase

Netlify Functions

Distribuire i webhook come funzioni serverless Netlify

Riferimenti API correlati

Create Webhook

Creare e configurare endpoint webhook tramite codice

List Webhooks

Recuperare e gestire gli endpoint webhook
Ultima modifica il 26 settembre 2026