Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.
Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.
Our webhook implementation follows the Standard Webhooks specification, ensuring compatibility with industry best practices and existing webhook libraries.
The Dodo Payments webhooks portal has been rebuilt with a native dashboard experience. Your existing endpoints, signing secrets, signature verification, event names, and webhook payloads are unchanged. No integration work is needed.
Where things live.
Under Developer → Webhooks — the Endpoints, Event catalog, Logs, Activity, and Settings tabs.
On an individual endpoint — the Overview tab, carrying delivery stats, the signing secret and Replay history, plus the Testing and Advanced tabs and the bulk replay actions.
On a message — opened from the Logs tab, where each delivery attempt can be replayed on its own without opening the endpoint.
1
Access Webhook Settings
Navigate to the Dodo Payments Dashboard and go to Developer → Webhooks.
2
Create Webhook Endpoint
Click Add endpoint to open the endpoint creation side sheet.
3
Enter Endpoint URL or Choose Integration
Enter the URL where you want to receive webhook events, or select an integration connector to route events to a third-party service (Slack, Discord, Zapier, Resend, etc.).
4
Select Events to Receive
Choose the specific events your endpoint should listen for. Events are organized in a searchable tree grouped by resource. You can select individual events or a parent resource to receive all related events.
Only selected events will trigger webhooks to your endpoint, helping you avoid unnecessary traffic and processing.
5
Create Endpoint
Click Create endpoint to save your configuration.
6
Get Secret Key
Your webhook signing secret is displayed on the endpoint’s Overview tab. You’ll use this to verify the authenticity of received webhooks.
Keep your webhook secret key secure and never expose it in client-side code or public repositories.
7
Rotate Secret (Optional)
If needed, you can rotate your webhook secret for enhanced security. Click Rotate secret, alongside the secret on the Overview tab.
Rotating the secret will expire it and replace it with a new one. The old secret will only be valid for the next 24 hours. Afterward, trying to verify with the old secret will fail.
Use secret rotation periodically or immediately if you suspect your current secret has been compromised.
Instead of building your own webhook receiver, you can route webhook events directly to third-party services using integration connectors. This eliminates the need to write and maintain custom webhook handlers for popular platforms.
A connector carries a transformation that converts the Dodo Payments event into the shape the destination expects. Which details you supply depends on the destination:
Connector type
What you provide
Destinations
Incoming webhook URL
A webhook URL you create in the vendor’s own dashboard. No API key.
The connector picker in the dashboard shows the full set currently available to your business, so treat the table above as the destinations with step-by-step setup instructions rather than an exhaustive list. See External Integrations for what each destination can do once events reach it.
Pick a connector while creating or editing an endpoint, and the side sheet shows setup instructions written for that destination — for example, how to create an incoming webhook URL in Slack, or where to find your Resend API key. Before you save, run the connector transformation test to confirm the event is converted correctly for the destination.
Use a connector to reach a supported destination without writing code. If you need custom logic, use a standard endpoint with a transformation instead.
You can configure which specific events each webhook endpoint should receive.
1
Navigate to Webhook Endpoints
Go to your Dodo Payments Dashboard and navigate to Developer → Webhooks.
2
Select Your Endpoint
Click on the webhook endpoint you want to configure.
3
Open Event Configuration
Click Edit to open the endpoint configuration side sheet.
4
Browse Event Types
The event type selector displays all available webhook events organized in a searchable tree, grouped by resource (e.g., payment, subscription, dispute). Use the search bar to quickly find specific events by name or keyword.
5
Select Events
Check the boxes next to the events you want to receive. You can:
Select a parent resource to receive all related events
Mix and match specific events based on your needs
6
Save Configuration
Click Save to apply your changes, or Cancel to discard modifications.
If you deselect all events, your webhook endpoint will not receive any notifications. Make sure to select at least the events your application needs to function properly.
Go to Developer → Webhooks and open the Event catalog tab. It lists every event type Dodo Payments can send, so you can see what is available before subscribing an endpoint to it. Select an event to view its schema and an example payload, which is the quickest way to check the shape of a field you plan to read.
Webhook Events Guide
Browse the same events as reference documentation, grouped by resource.
If a webhook delivery fails, Dodo Payments automatically retries with exponential backoff to prevent overwhelming your system.
Attempt
Delay
Description
1
Immediately
First retry happens right away
2
5 seconds
Second attempt after short delay
3
5 minutes
Third attempt with increased backoff
4
30 minutes
Fourth attempt continuing backoff
5
2 hours
Fifth attempt with extended delay
6
5 hours
Sixth attempt with longer delay
7
10 hours
Seventh attempt with maximum delay
8
10 hours
Final attempt - webhook marked as failed if unsuccessful
Maximum of 8 retry attempts per webhook event. For example, if a webhook fails three times before succeeding, the total delivery time is approximately 35 minutes and 5 seconds from the first attempt.
Use the Dodo Payments dashboard to manually retry individual messages or bulk recover all failed messages at any time.
La verifica della firma è il metodo supportato per autenticare un webhook. Dimostra che la richiesta è stata firmata con il tuo segreto webhook, cosa che un controllo a livello di rete non può fare.Le consegne dei webhook vengono inviate da un insieme di indirizzi IP di origine appartenenti alla nostra infrastruttura di consegna. Questo insieme cambia di tanto in tanto, quindi considera gli indirizzi come un dettaglio operativo e non come una proprietà fissa dell’integrazione.
Non utilizzare un elenco di indirizzi IP di origine consentiti come meccanismo di autenticazione. Un elenco di indirizzi consentiti mostra solo da dove proviene una richiesta, non che sia autentica o non modificata: verifica l’intestazione webhook-signature su ogni richiesta, come descritto in Verifica delle firme.
Se la tua infrastruttura si trova dietro un firewall che richiede un elenco di indirizzi consentiti esplicito, considera quanto segue:
Non codificare gli indirizzi in modo permanente. Gli intervalli vengono aggiunti e ritirati nel tempo e una regola obsoleta blocca silenziosamente le consegne.
Richiedi gli intervalli attuali a support@dodopayments.com prima di configurare un firewall restrittivo, così lavorerai con un elenco aggiornato.
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 per evitare consegne perse.
Mantieni attiva la verifica della firma indipendentemente dalle regole di rete che aggiungi.
Sulle piattaforme serverless e di hosting gestito, il filtraggio degli IP in entrata è spesso non disponibile o poco pratico da mantenere. In questi ambienti, la verifica della firma è il controllo corretto e non è necessario alcun elenco di indirizzi consentiti.
Una consegna bloccata viene trattata come qualsiasi altro errore e ritentata secondo la pianificazione descritta in Nuovi tentativi automatici. Se le regole del firewall hanno causato il fallimento delle consegne, puoi reinviarle dopo aver corretto le regole: consulta Riproduzione e recupero dei messaggi.
Utilizza sempre URL HTTPS per gli endpoint webhook. Gli endpoint HTTP sono vulnerabili agli attacchi man-in-the-middle ed espongono i dati del webhook.
Respond immediately
Restituisci immediatamente un codice di stato 200 alla ricezione del webhook. Elabora l’evento in modo asincrono per evitare timeout.
Implementa l’idempotenza utilizzando l’intestazione webhook-id per elaborare in sicurezza più volte lo stesso evento senza effetti collaterali.
Secure your webhook secret
Archivia il segreto webhook in modo sicuro utilizzando variabili d’ambiente o un gestore di segreti. Non eseguire mai il commit dei segreti nel controllo versione.
Tipo di risorsa. Uno tra: Payment, Subscription, Refund, Dispute, LicenseKey, CreditLedgerEntry, CreditBalanceLow, AbandonedCheckout, DunningAttempt, EntitlementGrant o Payout.
I campi aggiuntivi variano in base al tipo di evento. Consulta la documentazione specifica dell’evento per gli schemi completi.
Puoi testare l’integrazione webhook direttamente dalla dashboard Dodo Payments per assicurarti che l’endpoint funzioni correttamente prima di andare in produzione.
1
Navigate to Webhooks
Vai alla Dashboard Dodo Payments e accedi a Developer → Webhooks.
2
Select Your Endpoint
Fai clic sull’endpoint webhook per accedere alla relativa pagina dei dettagli.
3
Open Testing Tab
Fai clic sulla scheda Testing per accedere all’interfaccia di test dei webhook.
La scheda Testing invia un payload di esempio a questo endpoint, così puoi verificare il tuo ricevitore.
1
Select Event Type
Utilizza Select an event type per scegliere l’evento da testare, ad esempio payment.succeeded o payment.failed.
2
Send Example
Fai clic su Send example. Il payload di esempio viene consegnato all’URL del tuo endpoint esattamente come un evento reale e firmato allo stesso modo.
I messaggi non riusciti inviati dalla scheda Testing non vengono ritentati. Usala per verificare il ricevitore, non per testare la pianificazione dei nuovi tentativi.
3
Check Your Endpoint
La scheda registra quando è stato inviato l’Last example sent. Conferma che l’evento sia arrivato, che la verifica della firma sia riuscita e che tu abbia restituito un codice di stato 2xx.
Testa accuratamente il gestore del webhook utilizzando l’interfaccia di test della dashboard prima di elaborare gli eventi di produzione. Questo aiuta a identificare e correggere tempestivamente i problemi.
Inoltra in tempo reale gli eventi webhook reali dal tuo account in modalità test al server di sviluppo locale:
dodo wh listen
La CLI apre una connessione WebSocket a Dodo Payments e inoltra ogni evento webhook al tuo endpoint locale (ad es. http://localhost:3000/webhook), conservando tutte le intestazioni, comprese quelle della firma, per testare la verifica.
Il listener funziona solo con chiavi API in test mode. Esegui dodo login e seleziona Test Mode prima di utilizzare questo comando.
Invia payload webhook simulati a qualsiasi endpoint senza creare transazioni reali:
dodo wh trigger
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 supporta tutti i 47 tipi di evento che Dodo Payments consegna, incluse le categorie di abbonamenti, pagamenti, rimborsi, contestazioni, chiavi di licenza, payout, crediti, checkout abbandonati, solleciti di pagamento e concessioni di entitlement: consulta Supported Webhook Events per l’elenco completo.
I payload webhook simulati da dodo wh trigger non sono firmati. Durante i test, utilizza unsafe_unwrap() invece di unwrap() nel gestore webhook.
CLI Webhook Testing Docs
Consulta la documentazione completa sui test dei webhook con la CLI
Aggiungi intestazioni HTTP personalizzate a tutte le richieste webhook inviate al tuo endpoint. È utile per l’autenticazione, il routing o l’aggiunta di metadati.
1
Add Headers
Nella sezione “Custom Headers”, inserisci una Key e un Value per ogni intestazione personalizzata.
2
Add Multiple Headers
Fai clic sul pulsante + per aggiungere altre intestazioni personalizzate secondo necessità.
Le tue intestazioni personalizzate sono incluse in tutte le richieste webhook a questo endpoint.
Le trasformazioni consentono di modificare il payload di un webhook e, facoltativamente, reindirizzarlo a un URL diverso. Questa potente funzionalità ti permette di:
Modificare la struttura del payload prima dell’elaborazione
Instradare i webhook a endpoint diversi in base al contenuto
Aggiungere o rimuovere campi dal payload
Trasformare i formati dei dati
1
Enable Transformations
Attiva l’interruttore Enabled per abilitare la funzionalità di trasformazione.
2
Configure Transformation
Fai clic su Edit transformation per definire le regole di trasformazione utilizzando JavaScript.
3
Test Transformation
Utilizza l’interfaccia di test delle trasformazioni per verificare che la trasformazione funzioni correttamente prima di andare in produzione.
Le trasformazioni possono influire sulle prestazioni di consegna dei webhook. Esegui test approfonditi e mantieni la logica di trasformazione semplice ed efficiente.
La scheda Logs offre una visibilità completa sullo stato di consegna dei webhook, consentendoti di monitorare, eseguire il debug e gestire gli eventi webhook in modo efficace.
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
Utilizza la barra di ricerca per trovare messaggi specifici per 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, 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, così puoi reinviare quel singolo messaggio senza lasciare la pagina.
Vai a Developer → Webhooks e apri la scheda Activity per visualizzare le prestazioni di consegna tra i tuoi endpoint.Delivery activity traccia i tentativi nel tempo, raggruppandoli come Attempts per 5 minutes, Attempts per hour o Attempts per day a seconda dell’intervallo. Ogni barra è suddivisa per risultato; passando il mouse su un segmento vengono mostrati lo stato, il numero di tentativi e la relativa percentuale sul totale. In un endpoint, Delivery stats (last 24h) nella scheda Overview riepiloga le stesse informazioni dell’ultimo giorno.
La colonna Error rate (24h) nella scheda Endpoints indica immediatamente quali endpoint richiedono attenzione, prima ancora che tu ne apra uno.
Apri l’endpoint da Developer → Webhooks. Sono disponibili tre modalità, ognuna delle quali opera solo su quell’endpoint. L’intervallo da impostare dipende dalla modalità:
Modalità
Funzione
Impostazioni
Recover failed messages
Riproduce ogni messaggio destinato a questo endpoint la cui consegna è fallita.
Un punto di partenza: 8 hours ago, Yesterday, 3 days ago, Last week o 2 weeks ago
Replay missing messages
Riproduce i messaggi che non sono mai stati inviati a questo endpoint, ad esempio dopo averlo sottoscritto a un nuovo tipo di evento.
Gli stessi punti di partenza
Bulk replay messages
Riproduce i messaggi corrispondenti ai filtri scelti, inclusi quelli già consegnati correttamente.
Limiti Since e Until, predefiniti alle ultime due settimane, più tipi di evento, canale o tag opzionali
1
Open More Actions
Nell’endpoint, apri More actions e scegli una delle tre modalità precedenti.
2
Set the Range
Inserisci l’intervallo richiesto dalla modalità, come indicato nella tabella.
3
Start the Run
Fai clic su Recover o Replay, a seconda della modalità scelta.
Ogni esecuzione viene visualizzata in Replay history nella scheda Overview dell’endpoint, con modalità, intervallo temporale, stato e numero di messaggi reinviati.
Ricevi una notifica email quando le consegne dei webhook a un endpoint non riescono, così puoi risolvere i problemi prima che si trasformino in un arretrato.
1
Navigate to Settings Tab
Vai a Developer → Webhooks e apri la scheda Settings.
2
Find Email Alerting
Individua la scheda Email alerting.
3
Configure Email Addresses
Inserisci gli indirizzi che devono ricevere gli avvisi. Separa più indirizzi con virgole e lascia vuoto il campo per disattivare gli avvisi.
4
Save
Fai clic su Save per applicare le modifiche.
Attiva gli avvisi email per individuare tempestivamente i problemi di consegna dei webhook e mantenere integrazioni affidabili.
Pronto a distribuire il gestore webhook in produzione? Forniamo guide specifiche per piattaforma che ti aiutano a distribuire i webhook sui principali provider cloud, seguendo le best practice di ciascuna piattaforma.
Vercel
Distribuisci i webhook su Vercel con funzioni serverless
Cloudflare Workers
Esegui i webhook sulla rete edge di Cloudflare
Supabase Edge Functions
Integra i webhook con Supabase
Netlify Functions
Distribuisci i webhook come funzioni serverless Netlify
Ogni guida per piattaforma include la configurazione dell’ambiente, la verifica della firma e i passaggi di distribuzione specifici per quel provider.