
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
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
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: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.Configuring Subscribed Events
Configure which events each webhook endpoint receives.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
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.Save Configuration
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
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 stato200, 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:Idempotenza
Ogni webhook include un headerwebhook-id univoco. Memorizza questo ID per rilevare e ignorare gli eventi duplicati, poiché i retry possono consegnare 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 campotimestamp; 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 headerwebhook-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. ImpostaDODO_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.
unwrap / unsafeUnwrap in TypeScript, unwrap / unsafe_unwrap in Python e Unwrap / UnsafeUnwrap in Go.
Verifica manuale (alternativa)
Se non usi un SDK, verifica autonomamente la firma:- Crea il contenuto firmato unendo
webhook-id,webhook-timestampe 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. - 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. - Calcola l’HMAC-SHA256 del contenuto firmato con la signing key e codifica il risultato in base64.
- L’header
webhook-signaturecontiene una o più firme separate da spazi, ciascuna nel formatov1,<base64-signature>. La richiesta è valida se una qualsiasi firmav1corrisponde alla tua. Confronta usando una funzione constant-time. - Rifiuta la richiesta se
webhook-timestampè troppo distante dall’ora corrente, per prevenire gli attacchi di replay. Le librerie Standard Webhooks consentono 5 minuti.
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’headerwebhook-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.
Rispondere ai webhook
Il tuo webhook handler deve restituire un2xx 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-idper rilevare e ignorare gli eventi duplicati. - Proteggi la tua secret key. Memorizza
DODO_PAYMENTS_WEBHOOK_KEYnelle variabili d’ambiente o in un secrets manager, mai nel controllo versione.
Struttura del payload del webhook
Formato della richiesta
Header
Corpo della richiesta
payment.succeeded, subscription.active).Payload di esempio
Event Types
Event Payloads
Handle Payment Failures
payment.failed e recupera i pagamenti rifiutatiTestare i webhook
Inviare un evento di esempio
Testa la tua integrazione webhook direttamente dal dashboard:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx.Esempio di implementazione
Implementazione completa in Express.js con verifica e gestione dei webhook: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:http://localhost:3000/webhook), mantenendo tutti gli header per testare la verifica delle firme.
dodo login e seleziona prima Test Mode.Attivare eventi webhook simulati
Invia payload webhook simulati a qualsiasi endpoint senza creare transazioni reali:subscription.past_due o subscription.unpaused. Consulta Supported Webhook Events per l’elenco completo.
CLI Webhook Testing Docs
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.Open Advanced Tab
Configure Rate Limit
Set Your Limit
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.Add Headers
Add Multiple Headers
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
Enable Transformations
Configure Transformation
handler().Test Transformation
Monitorare i log dei webhook
La scheda Logs fornisce visibilità sullo stato di consegna dei webhook.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 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
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.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:Open More Actions
Set the Range
Start the Run