Skip to main content
Webhook Cover Image
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.

Key Features

Real-time Delivery

Receive instant notifications when events occur

Secure by Default

HMAC SHA256 signature verification included

Automatic Retries

Built-in retry logic with exponential backoff

Event Filtering

Subscribe only to events you need

Getting Started

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.

Integration Connectors

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.

How Connectors Work

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

Setting Up a Connector

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.

Configuring Subscribed Events

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 individual events (e.g., payment.succeeded, payment.failed)
  • 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.

Event Catalog

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.

Webhook Delivery

Timeouts

Webhooks have a 15-second timeout window for both connection and read operations. Ensure your endpoint responds quickly to avoid timeouts.
Process webhooks asynchronously by acknowledging receipt immediately with a 200 status code, then handling the actual processing in the background.

Automatic Retries

If a webhook delivery fails, Dodo Payments automatically retries with exponential backoff to prevent overwhelming your system.
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.

Idempotency

Each webhook event includes a unique webhook-id header. Use this identifier to implement idempotency and prevent duplicate processing.
Always implement idempotency checks. Due to retries, you may receive the same event multiple times.

Event Ordering

Webhook events may arrive out of order due to retries or network conditions. Design your system to handle events in any sequence.
You will receive the latest payload at the time of delivery, regardless of when the webhook event was originally emitted.

Securing Webhooks

To ensure the security of your webhooks, always validate the payloads and use HTTPS.

Verifying Signatures

Each webhook request includes a webhook-signature header, an HMAC SHA256 signature of the webhook payload and timestamp, signed with your secret key. All official SDKs include built‑in helpers to securely validate and parse incoming webhooks. Two methods are available:
  • unwrap(): Verifies signatures using your webhook secret key
  • unsafe_unwrap(): Parses payloads without verification
Provide your webhook secret via DODO_PAYMENTS_WEBHOOK_KEY when initializing the Dodo Payments client.

Manual verification (alternative)

If you are not using an SDK, you can verify signatures yourself following the Standard Webhooks spec:
  1. Build the signed message by concatenating webhook-id, webhook-timestamp, and the exact raw stringified payload, separated by periods (.).
  2. Compute the HMAC SHA256 of that string using your webhook secret key from the Dashboard.
  3. Compare the computed signature to the webhook-signature header. If they match, the webhook is authentic.
We follow the Standard Webhooks specification. You can use their libraries to verify signatures: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. For event payload formats, see the Webhook Payload.

Indirizzi IP di origine

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.

Rispondere ai webhook

  • Il gestore del webhook deve restituire un 2xx status code per confermare la ricezione dell’evento.
  • Qualsiasi altra risposta verrà trattata come un errore e il webhook verrà ritentato.

Best practice

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

Struttura del payload webhook

Comprendere la struttura del payload webhook ti aiuta a analizzare ed elaborare correttamente gli eventi.

Formato della richiesta

Intestazioni

string
obbligatorio
Identificatore univoco di 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 dell’invio del webhook.

Corpo della richiesta

string
obbligatorio
Identificatore della tua attività Dodo Payments.
string
obbligatorio
Tipo di evento che ha attivato questo webhook (ad es. 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 evento webhook disponibili

Event Payloads

Visualizza gli schemi dettagliati del payload per ogni evento

Handle Payment Failures

Reagisci a payment.failed e recupera i pagamenti rifiutati

Test dei webhook

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.

Inviare un evento di esempio

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.

Esempio di implementazione

Ecco un’implementazione completa con Express.js che mostra la verifica e la gestione dei webhook:
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.

Test dei webhook con la CLI

La Dodo Payments CLI fornisce due comandi per testare i webhook durante lo sviluppo locale, senza dover lasciare il terminale.

Ascoltare localmente i webhook in tempo reale

Inoltra in tempo reale gli eventi webhook reali dal tuo account in modalità test al server di sviluppo locale:
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.

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

Impostazioni avanzate

La scheda Advanced offre opzioni di configurazione aggiuntive per perfezionare il comportamento dell’endpoint webhook.

Limitazione della frequenza (throttling)

Controlla la frequenza con cui gli eventi webhook vengono consegnati al tuo endpoint per evitare di sovraccaricare il sistema.
1

Open Advanced Tab

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

Configure Rate Limit

Nella sezione “Rate Limit (throttling)”, fai clic su Edit per modificare le impostazioni del limite di frequenza.
Per impostazione predefinita, ai webhook non viene applicato alcun limite di frequenza, quindi gli eventi vengono consegnati non appena si verificano.
3

Set Your Limit

Configura il limite di frequenza desiderato per controllare la frequenza di consegna dei webhook ed evitare il sovraccarico del sistema.
Utilizza la limitazione della frequenza quando il gestore webhook ha bisogno di tempo per elaborare gli eventi o quando vuoi raggruppare più eventi.

Intestazioni personalizzate

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.

Trasformazioni

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.
Le trasformazioni sono particolarmente utili per:
  • Convertire dati tra formati diversi
  • Filtrare gli eventi in base a criteri specifici
  • Aggiungere campi calcolati al payload
  • Instradare gli eventi a microservizi diversi

Monitoraggio dei log dei webhook

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.

Monitoraggio dell’attività

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.

Riproduzione e recupero dei messaggi

Il modo in cui reinvii un messaggio dipende da quanti messaggi devi gestire:
  • Un messaggio: aprilo dalla scheda Logs e utilizza l’azione Replay sul tentativo. Non è necessario aprire l’endpoint.
  • Un intervallo di messaggi: apri l’endpoint, poiché le modalità collettive operano su un solo endpoint alla volta.

Riproduzione collettiva

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à:
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.

Avvisi email

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.

Distribuzione su piattaforme cloud

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.

Riferimenti API correlati

Create Webhook

Riferimento API per creare e configurare gli endpoint webhook tramite codice

List Webhooks

Riferimento API per recuperare e gestire gli endpoint webhook
Ultima modifica il 21 agosto 2026