Ricevi notifiche in tempo reale quando si verificano eventi in Dodo Payments. Automatizza i flussi di lavoro e mantieni i tuoi sistemi sincronizzati con la consegna immediata degli eventi.
I webhooks forniscono notifiche in tempo reale quando si verificano eventi specifici nel tuo account Dodo Payments. Utilizza i webhooks per automatizzare i flussi di lavoro, aggiornare il tuo database, inviare notifiche e mantenere i tuoi sistemi sincronizzati.
La nostra implementazione dei webhook segue la specifica Standard Webhooks, garantendo compatibilità con le migliori pratiche del settore e le librerie di webhook esistenti.
Naviga al Dashboard di DodoPayments e vai a Settings > Webhooks.
2
Crea un endpoint Webhook
Clicca su Add Webhook per creare un nuovo endpoint webhook.
3
Aggiungi URL dell'endpoint
Inserisci l’URL dove desideri ricevere gli eventi webhook.
4
Seleziona eventi da ricevere
Scegli gli eventi specifici a cui il tuo endpoint webhook dovrebbe ascoltare selezionandoli dall’elenco degli eventi.
Solo gli eventi selezionati attiveranno i webhook al tuo endpoint, aiutandoti a evitare traffico eccessivo e elaborazione non necessaria.
5
Ottieni la chiave segreta
Ottieni il tuo webhook Secret Key dalla pagina delle impostazioni. Utilizzerai questo per verificare l’autenticità dei webhook ricevuti.
Tieni al sicuro la tua chiave segreta del webhook e non esporla mai nel codice lato client o nei repository pubblici.
6
Ruota segreto (opzionale)
Se necessario, puoi ruotare il tuo segreto webhook per una maggiore sicurezza. Clicca sul pulsante Ruota segreto nelle impostazioni del tuo webhook.
Ruotare il segreto scadrà e sostituirà con uno nuovo. Il vecchio segreto sarà valido solo per le prossime 24 ore. Dopo, provare a verificare con il vecchio segreto fallirà.
Utilizza la rotazione del segreto periodicamente o immediatamente se sospetti che il tuo attuale segreto sia stato compromesso.
Vai al tuo Dashboard di Dodo Payments e naviga a Settings > Webhooks.
2
Seleziona il tuo endpoint
Clicca sull’endpoint webhook che desideri configurare.
3
Apri le impostazioni degli eventi
Nella pagina dei dettagli del webhook, vedrai una sezione “Eventi sottoscritti”. Clicca sul pulsante Modifica per modificare le tue iscrizioni agli eventi.
L’interfaccia mostra tutti gli eventi webhook disponibili organizzati in una struttura gerarchica. Gli eventi sono raggruppati per categoria (ad es., dispute, payment, subscription).
2
Cerca e filtra
Usa la barra di ricerca per trovare rapidamente eventi specifici digitando nomi di eventi o parole chiave.
3
Seleziona eventi
Seleziona le caselle accanto agli eventi che desideri ricevere. Puoi:
Selezionare eventi secondari individuali (ad es., dispute.accepted, dispute.challenged)
Selezionare eventi principali per ricevere tutti gli eventi secondari correlati
Mescolare e abbinare eventi specifici in base alle tue esigenze
4
Rivedi i dettagli dell'evento
Passa il mouse sull’icona informativa (ⓘ) accanto a ciascun evento per vedere una descrizione di quando viene attivato quell’evento.
5
Salva configurazione
Clicca su Salva per applicare le tue modifiche, o Annulla per scartare le modifiche.
Se deselezioni tutti gli eventi, il tuo endpoint webhook non riceverà alcuna notifica. Assicurati di selezionare almeno gli eventi di cui la tua applicazione ha bisogno per funzionare correttamente.
I webhooks hanno una finestra di timeout di 15 secondi sia per le operazioni di connessione che di lettura. Assicurati che il tuo endpoint risponda rapidamente per evitare timeout.
Elabora i webhooks in modo asincrono riconoscendo immediatamente la ricezione con un codice di stato 200, quindi gestendo l’elaborazione effettiva in background.
Se la consegna di un webhook fallisce, Dodo Payments riprova automaticamente con un backoff esponenziale per evitare di sovraccaricare il tuo sistema.
Tentativo
Ritardo
Descrizione
1
Immediatamente
Il primo tentativo avviene subito
2
5 secondi
Secondo tentativo dopo un breve ritardo
3
5 minuti
Terzo tentativo con backoff aumentato
4
30 minuti
Quarto tentativo continuando il backoff
5
2 ore
Quinto tentativo con ritardo esteso
6
5 ore
Sesto tentativo con ritardo più lungo
7
10 ore
Settimo tentativo con ritardo massimo
8
10 ore
Tentativo finale - webhook contrassegnato come fallito se non riuscito
Massimo di 8 tentativi di ripetizione per ogni evento webhook. Ad esempio, se un webhook fallisce tre volte prima di avere successo, il tempo totale di consegna è di circa 35 minuti e 5 secondi dal primo tentativo.
Utilizza il dashboard di Dodo Payments per ripetere manualmente messaggi singoli o recuperare in blocco tutti i messaggi falliti in qualsiasi momento.
Ogni evento webhook include un header unico webhook-id. Utilizza questo identificatore per implementare l’idempotenza e prevenire l’elaborazione duplicata.
Copia
Chiedi all'IA
// Example: Storing webhook IDs to prevent duplicate processingconst processedWebhooks = new Set();app.post('/webhook', (req, res) => { const webhookId = req.headers['webhook-id']; if (processedWebhooks.has(webhookId)) { return res.status(200).json({ received: true }); } processedWebhooks.add(webhookId); // Process the webhook...});
Implementa sempre controlli di idempotenza. A causa dei ritentativi, potresti ricevere lo stesso evento più volte.
Gli eventi webhook possono arrivare in ordine errato a causa di ritentativi o condizioni di rete. Progetta il tuo sistema per gestire eventi in qualsiasi sequenza.
Riceverai il payload più recente al momento della consegna, indipendentemente da quando l’evento webhook è stato originariamente emesso.
Ogni richiesta webhook include un header webhook-signature, una firma HMAC SHA256 del payload del webhook e del timestamp, firmata con la tua chiave segreta.
Implementa l’idempotenza utilizzando l’header webhook-id per elaborare in modo sicuro lo stesso evento più volte senza effetti collaterali.
Sicura la tua chiave segreta del webhook
Conserva la tua chiave segreta del webhook in modo sicuro utilizzando variabili di ambiente o un gestore di segreti. Non commettere mai segreti nel controllo delle versioni.
Puoi testare la tua integrazione webhook direttamente dal dashboard di Dodo Payments per assicurarti che il tuo endpoint funzioni correttamente prima di andare in produzione.
Ecco un’implementazione completa di Express.js che mostra la verifica e la gestione dei webhook:
Copia
Chiedi all'IA
import { Webhook } from "standardwebhooks";import express from "express";const app = express();app.use(express.json());const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);app.post('/webhook/dodo-payments', async (req, res) => { try { // Extract webhook headers const webhookHeaders = { "webhook-id": req.headers["webhook-id"] as string, "webhook-signature": req.headers["webhook-signature"] as string, "webhook-timestamp": req.headers["webhook-timestamp"] as string, }; // Verify the webhook signature const payload = JSON.stringify(req.body); await webhook.verify(payload, webhookHeaders); // Acknowledge receipt immediately res.status(200).json({ received: true }); // Process webhook asynchronously processWebhookAsync(req.body).catch(console.error); } catch (error) { console.error('Webhook verification failed:', error); res.status(400).json({ error: 'Invalid signature' }); }});async function processWebhookAsync(data: any) { // Handle the webhook event based on type switch (data.type) { case 'payment.succeeded': await handlePaymentSucceeded(data); break; case 'subscription.created': await handleSubscriptionCreated(data); break; // Add more event handlers... }}
Testa a fondo il tuo gestore webhook utilizzando l’interfaccia di test del dashboard prima di elaborare eventi di produzione. Questo aiuta a identificare e risolvere i problemi in anticipo.
Controlla la velocità con cui gli eventi webhook vengono consegnati al tuo endpoint per evitare di sovraccaricare il tuo sistema.
1
Accedi alle impostazioni di limitazione della velocità
Nella scheda Avanzate, individua la sezione “Limitazione della velocità (throttling)”.
2
Configura la limitazione della velocità
Clicca sul pulsante Modifica per modificare le impostazioni di limitazione della velocità.
Per impostazione predefinita, i webhook non hanno “Nessuna limitazione della velocità” applicata, il che significa che gli eventi vengono consegnati non appena si verificano.
3
Imposta limiti
Configura il tuo limite di velocità desiderato per controllare la frequenza di consegna dei webhook e prevenire sovraccarichi del sistema.
Utilizza la limitazione della velocità quando il tuo gestore webhook ha bisogno di tempo per elaborare gli eventi o quando desideri raggruppare più eventi insieme.
Aggiungi intestazioni HTTP personalizzate a tutte le richieste webhook inviate al tuo endpoint. Questo è utile per l’autenticazione, il routing o l’aggiunta di metadati alle tue richieste webhook.
1
Aggiungi intestazione personalizzata
Nella sezione “Intestazioni personalizzate”, inserisci una Chiave e un Valore per la tua intestazione personalizzata.
2
Aggiungi più intestazioni
Clicca sul pulsante + per aggiungere ulteriori intestazioni personalizzate secondo necessità.
3
Salva configurazione
Le tue intestazioni personalizzate saranno incluse in tutte le richieste webhook a questo endpoint.
Le trasformazioni ti consentono di modificare un payload di webhook e reindirizzarlo a un URL diverso. Questa potente funzionalità ti consente di:
Modificare la struttura del payload prima dell’elaborazione
Reindirizzare i webhook a diversi endpoint in base al contenuto
Aggiungere o rimuovere campi dal payload
Trasformare i formati dei dati
1
Abilita trasformazioni
Attiva l’interruttore Abilitato per attivare la funzionalità di trasformazione.
2
Configura trasformazione
Clicca su Modifica trasformazione per definire le tue regole di trasformazione.
Puoi utilizzare JavaScript per trasformare il payload del webhook e specificare un URL di destinazione diverso.
3
Testa la trasformazione
Usa l’interfaccia di test per verificare che la tua trasformazione funzioni correttamente prima di andare in produzione.
Le trasformazioni possono influire significativamente sulle prestazioni di consegna dei webhook. Testa a fondo e mantieni la logica di trasformazione semplice ed efficiente.
La scheda Log fornisce una visibilità completa sullo stato di consegna dei tuoi webhook, consentendoti di monitorare, eseguire il debug e gestire efficacemente gli eventi webhook.
Rimani informato sulla salute dei tuoi webhook con notifiche email automatiche. Quando le consegne dei webhook iniziano a fallire o il tuo endpoint smette di rispondere, riceverai avvisi via email in modo da poter affrontare rapidamente i problemi e mantenere le tue integrazioni in esecuzione senza problemi.
Vai al tuo Dashboard di Dodo Payments e naviga a Dashboard → Webhooks → Avvisi.
2
Abilita notifiche email
Attiva le Notifiche email per iniziare a ricevere avvisi sui problemi di consegna dei webhook.
3
Configura indirizzo email
Inserisci l’indirizzo email dove desideri ricevere gli avvisi webhook. Invieremo notifiche a questo indirizzo quando si verificano determinati eventi con la tua configurazione webhook, come problemi di consegna che potrebbero influenzare le tue integrazioni.
Abilita gli avvisi via email per catturare precocemente i problemi di consegna dei webhook e mantenere integrazioni affidabili. Sarai avvisato quando le consegne falliscono o il tuo endpoint diventa non responsivo.
Pronto a distribuire il tuo gestore webhook in produzione? Forniamo guide specifiche per piattaforma per aiutarti a distribuire i webhook ai fornitori di cloud popolari con le migliori pratiche per ciascuna piattaforma.