Vai al contenuto principale
Immagine di copertura Webhook
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.

Caratteristiche principali

Consegna in tempo reale

Ricevi notifiche istantanee quando si verificano eventi

Sicuro per impostazione predefinita

Verifica della firma HMAC SHA256 inclusa

Ritenti automatici

Logica di ritentativo integrata con backoff esponenziale

Filtraggio degli eventi

Iscriviti solo agli eventi di cui hai bisogno

Iniziare

1

Accedi alle impostazioni del Webhook

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

Configurazione degli eventi sottoscritti

Puoi configurare quali eventi specifici desideri ricevere per ciascun endpoint webhook.

Accesso alla configurazione degli eventi

1

Naviga ai dettagli del Webhook

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.

Gestione delle iscrizioni agli eventi

1

Visualizza eventi disponibili

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.

Consegna del Webhook

Timeout

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.

Ritenti automatici

Se la consegna di un webhook fallisce, Dodo Payments riprova automaticamente con un backoff esponenziale per evitare di sovraccaricare il tuo sistema.
TentativoRitardoDescrizione
1ImmediatamenteIl primo tentativo avviene subito
25 secondiSecondo tentativo dopo un breve ritardo
35 minutiTerzo tentativo con backoff aumentato
430 minutiQuarto tentativo continuando il backoff
52 oreQuinto tentativo con ritardo esteso
65 oreSesto tentativo con ritardo più lungo
710 oreSettimo tentativo con ritardo massimo
810 oreTentativo 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.

Idempotenza

Ogni evento webhook include un header unico webhook-id. Utilizza questo identificatore per implementare l’idempotenza e prevenire l’elaborazione duplicata.
// Example: Storing webhook IDs to prevent duplicate processing
const 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.

Ordinamento degli eventi

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.

Sicurezza dei Webhook

Per garantire la sicurezza dei tuoi webhook, valida sempre i payload e utilizza HTTPS.

Verifica delle firme

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.

Verifica SDK (raccomandata)

Tutti gli SDK ufficiali includono helper integrati per validare e analizzare in modo sicuro i webhook in arrivo. Sono disponibili due metodi:
  • unwrap(): Verifica le firme utilizzando la tua chiave segreta del webhook
  • unsafe_unwrap(): Analizza i payload senza verifica
Fornisci la tua chiave segreta del webhook tramite DODO_PAYMENTS_WEBHOOK_KEY durante l’inizializzazione del client Dodo Payments.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

Verifica manuale (alternativa)

Se non stai utilizzando un SDK, puoi verificare le firme tu stesso seguendo la specifica Standard Webhooks:
  1. Costruisci il messaggio firmato concatenando webhook-id, webhook-timestamp, e la stringa esatta raw stringificata payload, separati da punti (.).
  2. Calcola l’HMAC SHA256 di quella stringa utilizzando la tua chiave segreta del webhook dal Dashboard.
  3. Confronta la firma calcolata con l’header webhook-signature. Se corrispondono, il webhook è autentico.
Seguiamo la specifica Standard Webhooks. Puoi utilizzare le loro librerie per verificare le firme: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Per i formati dei payload degli eventi, vedere il Payload del Webhook.

Rispondere ai Webhook

  • Il tuo gestore webhook deve restituire un 2xx status code per riconoscere la ricezione dell’evento.
  • Qualsiasi altra risposta sarà trattata come un fallimento e il webhook verrà ripetuto.

Migliori pratiche

Utilizza sempre URL HTTPS per gli endpoint webhook. Gli endpoint HTTP sono vulnerabili ad attacchi man-in-the-middle e espongono i tuoi dati webhook.
Restituisci un codice di stato 200 immediatamente al ricevimento del webhook. Elabora l’evento in modo asincrono per evitare timeout.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Implementa l’idempotenza utilizzando l’header webhook-id per elaborare in modo sicuro lo stesso evento più volte senza effetti collaterali.
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.

Struttura del Payload del Webhook

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

Formato della richiesta

POST /your-webhook-url
Content-Type: application/json

Intestazioni

webhook-id
string
obbligatorio
Identificatore unico per questo evento webhook. Utilizzalo per controlli di idempotenza.
webhook-signature
string
obbligatorio
Firma HMAC SHA256 per verificare l’autenticità del webhook.
webhook-timestamp
string
obbligatorio
Timestamp Unix (in secondi) quando il webhook è stato inviato.

Corpo della richiesta

business_id
string
obbligatorio
Il tuo identificatore aziendale Dodo Payments.
type
string
obbligatorio
Tipo di evento che ha attivato questo webhook (ad es., payment.succeeded, subscription.created).
timestamp
string
obbligatorio
Timestamp formattato ISO 8601 di quando si è verificato l’evento.
data
object
obbligatorio
Payload specifico dell’evento contenente informazioni dettagliate sull’evento.

Esempio di Payload

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

Testare i Webhook

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.
Dettagli dell'Endpoint

Accesso all’interfaccia di test

1

Naviga ai Webhook

Vai al tuo Dashboard di Dodo Payments e naviga a Settings > Webhooks.
2

Seleziona il tuo endpoint

Clicca sul tuo endpoint webhook per accedere alla sua pagina dei dettagli.
3

Apri la scheda di test

Clicca sulla scheda Test per accedere all’interfaccia di test del webhook.

Testare il tuo Webhook

L’interfaccia di test fornisce un modo completo per testare il tuo endpoint webhook:
1

Seleziona il tipo di evento

Usa il menu a discesa per selezionare il tipo di evento specifico che desideri testare (ad es., payment.succeeded, payment.failed, ecc.).
Il menu a discesa contiene tutti i tipi di eventi webhook disponibili che il tuo endpoint può ricevere.
2

Rivedi schema e esempio

L’interfaccia mostra sia lo Schema (struttura dei dati) che l’Esempio (payload di esempio) per il tipo di evento selezionato.
3

Invia evento di test

Clicca sul pulsante Invia esempio per inviare un webhook di test al tuo endpoint.
Importante: I messaggi falliti inviati tramite l’interfaccia di test non verranno ripetuti. Questo è solo per scopi di test.

Verifica del tuo test

1

Controlla il tuo endpoint

Monitora i log del tuo endpoint webhook per confermare che l’evento di test sia stato ricevuto.
2

Verifica la firma

Assicurati che la tua verifica della firma funzioni correttamente con il payload di test.
3

Testa la risposta

Conferma che il tuo endpoint restituisca un codice di stato 2xx per riconoscere la ricezione.

Esempio di implementazione

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

Impostazioni avanzate

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

Limitazione della velocità (Throttling)

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.

Intestazioni personalizzate

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.

Trasformazioni

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

Monitoraggio dei log dei Webhook

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

Monitoraggio dell’attività

La scheda Attività fornisce informazioni in tempo reale sulle prestazioni di consegna dei tuoi webhook con analisi visive.
Attività

Avvisi via email

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.
Impostazioni di avviso Webhook che mostrano la configurazione delle notifiche email

Abilita avvisi via email

1

Naviga alle impostazioni di avviso

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.

Distribuzione su piattaforme cloud

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.
Ogni guida per piattaforma include configurazione dell’ambiente, verifica della firma e passaggi di distribuzione specifici per quel fornitore.