Windmill

Introduzione

Esegui uno script o un flusso Windmill ogni volta che si verifica un evento di Dodo Payments. Usalo per aggiornare un database, sincronizzare record con un altro sistema, inviare notifiche o eseguire la tua logica aziendale nel codice.

Il connettore Windmill invia ogni evento all’URL webhook di uno script o flusso Windmill. Ti servono uno script o flusso distribuito, un token Windmill che possa eseguirlo e l’accesso a Developer → Webhooks nella dashboard di Dodo Payments.

Iniziare

Open the Webhook Section

Nella dashboard di Dodo Payments, vai a Developer → Webhooks e fai clic su Add endpoint.

Finestra di dialogo per aggiungere un endpoint con Windmill selezionato nel menu a discesa Integration e i passaggi How to connect Windmill

Select Windmill

In Integration, seleziona Windmill. La dashboard carica il codice di trasformazione Windmill e mostra i passaggi di configurazione nel pannello How to connect Windmill.

Copy the Windmill Webhook URL

In Windmill, apri lo script o il flusso che deve gestire gli eventi. Nella scheda Triggers, apri Webhooks e copia l’URL webhook asincrono (UUID/Async). Quindi crea un token specifico per webhook per lo script o il flusso e copialo. Questo token può eseguire solo quello script o flusso.

Paste Webhook URL

Incolla l’URL webhook Windmill in Endpoint URL. L’URL deve usare HTTPS, quindi un’istanza Windmill self-hosted deve avere un indirizzo HTTPS pubblico. Il connettore Windmill non include un campo per la API key, quindi devi aggiungere il token dopo aver creato l’endpoint.

Select Events

Subscribed events elenca gli eventi supportati dal connettore Windmill. Mantieni solo gli eventi gestiti dal tuo script o flusso.

Configure Transformation

In Transformation code, modifica l’handler in modo che le chiavi di primo livello del payload corrispondano agli input del tuo script o flusso. Parti dagli esempi.

Test & Create

In Test this code, seleziona un tipo di evento e fai clic su Simulate per visualizzare un’anteprima del payload. Quindi fai clic su Create endpoint.

Add the Windmill Token

Subito dopo aver creato l’endpoint, apri la scheda Advanced. In Custom headers, fai clic su Add header. Inserisci Authorization come nome e Bearer, uno spazio e il tuo token come valore. Quindi fai clic su Save. Finché non salvi l’header, Windmill rifiuta le consegne e Dodo Payments le ritenta secondo il programma dei retry.Windmill accetta il token anche in un parametro di query token alla fine dell’URL. Windmill consiglia l’header, perché chiunque possa visualizzare un URL con un token può utilizzare il token.

Done

Gli eventi sottoscritti ora avviano le esecuzioni del tuo script o flusso. Per inviare un evento di test, apri la scheda Testing dell’endpoint, seleziona un tipo di evento e fai clic su Send example. In Windmill, l’esecuzione viene visualizzata nella pagina Runs con il trigger Webhook.

Esempi di codice di trasformazione

Ogni handler sostituisce webhook.payload con un oggetto piatto e mantiene webhook.url, il tuo URL webhook Windmill. Windmill passa ogni chiave di primo livello all’input dello script o flusso con lo stesso nome, quindi uno script per il primo esempio dichiara input come event_type, payment_id e amount. Gli importi di Dodo Payments sono espressi nell’unità più piccola della valuta, quindi gli esempi dividono per 100 e inviano il risultato come stringa, ad esempio "25.00". Per le valute senza decimali, come JPY e KRW, usa l’importo così com’è.

Payload del workflow di base

Invia i dettagli di un pagamento riuscito:

basic_workflow.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      payment_id: p.payment_id,
      amount: (p.total_amount / 100).toFixed(2),
      currency: p.currency,
      customer_email: p.customer.email,
      customer_name: p.customer.name,
      payment_method: p.payment_method || "unknown",
      timestamp: webhook.payload.timestamp,
      metadata: {
        business_id: p.business_id,
        product_id: p.product_cart ? p.product_cart.map(i => i.product_id).join(', ') : undefined
      }
    };
  }
  return webhook;
}

Handler del workflow per gli abbonamenti

Invia un evento subscription_started o subscription_cancelled quando un abbonamento diventa attivo o viene annullato:

subscription_workflow.js

function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        event_type: "subscription_started",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        customer_name: s.customer.name,
        product_id: s.product_id,
        amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
        currency: s.currency,
        frequency: s.payment_frequency_interval,
        next_billing: s.next_billing_date,
        customer_id: s.customer.customer_id,
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.payload = {
        event_type: "subscription_cancelled",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        cancelled_at: s.cancelled_at,
        cancel_at_next_billing: s.cancel_at_next_billing_date,
        customer_id: s.customer.customer_id,
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}

Handler del workflow per le contestazioni

Invia ogni evento di contestazione, impostando urgent su true quando si apre una contestazione:

dispute_workflow.js

function handler(webhook) {
  if (webhook.eventType.startsWith("dispute.")) {
    const d = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      dispute_id: d.dispute_id,
      payment_id: d.payment_id,
      amount: (d.amount / 100).toFixed(2),
      currency: d.currency,
      status: d.dispute_status,
      stage: d.dispute_stage,
      remarks: d.remarks || "",
      urgent: webhook.eventType === "dispute.opened",
      business_id: d.business_id,
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}

Casi d’uso comuni di Windmill

Database Operations

Aggiornare i record dei clienti in PostgreSQL o MySQL
Registrare gli eventi di pagamento in un data warehouse
Sincronizzare i dati con sistemi esterni
Aggiornare i livelli di inventario
Monitorare le metriche di analisi

Business Logic

Calcolare le metriche dei ricavi
Elaborare rimborsi e rettifiche
Gestire le modifiche del ciclo di vita degli abbonamenti
Generare report ed esportazioni
Convalidare i dati di pagamento

External Integrations

Inviare dati alle piattaforme di analisi
Aggiornare i sistemi CRM
Avviare campagne email
Creare eventi del calendario
Inviare notifiche SMS

Suggerimenti

Assegna ai payload key i nomi degli input dello script o flusso, perché Windmill associa ogni chiave di primo livello all’input con lo stesso nome.
Usa gli stessi nomi dei campi tra gli eventi, così un unico script può gestire diversi tipi di evento.
Includi il tipo di evento e timestamp. Gli eventi possono arrivare fuori ordine e timestamp consente allo script di ordinarli.
Usa l’URL webhook asincrono. L’URL sincrono attende il completamento dell’esecuzione e un’esecuzione che supera il timeout della consegna viene considerata una consegna non riuscita, che Dodo Payments ritenta.
Assicurati che lo script possa essere eseguito due volte per lo stesso evento, perché i retry possono consegnare un evento più di una volta.
Per ignorare un evento nel codice, imposta webhook.cancel = true prima di restituire il webhook. I log registrano una consegna ignorata come riuscita.
Usa gli error handlers di Windmill per ricevere una notifica quando un’esecuzione non riesce.

Risoluzione dei problemi

Workflows Not Triggering

Verifica che Endpoint URL sia l’URL webhook del tuo script o flusso e che l’endpoint sia abilitato.
Verifica che l’header Authorization contenga Bearer e un token valido. Un token specifico per webhook esegue solo il proprio script o flusso.
Verifica che lo script o il flusso sia distribuito. Il webhook esegue l’ultima versione distribuita, non una bozza.
Apri la scheda Logs in Developer → Webhooks per visualizzare la risposta di Windmill a ogni consegna.

Data Processing Issues

Verifica che le chiavi di primo livello del payload corrispondano per nome agli input dello script o flusso.
Verifica che ogni valore corrisponda al tipo del relativo input. Gli esempi inviano gli importi come stringhe.
Controlla l’esecuzione nella pagina Runs di Windmill, filtrando per il trigger Webhook. L’URL asincrono risponde non appena Windmill mette in coda l’esecuzione, quindi i log di Dodo Payments mostrano una consegna riuscita anche quando l’esecuzione non riesce.
Esegui lo script o il flusso in Windmill con un payload proveniente da Simulate.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introduzione

Iniziare

Esempi di codice di trasformazione

Payload del workflow di base

Handler del workflow per gli abbonamenti

Handler del workflow per le contestazioni

Casi d’uso comuni di Windmill

Suggerimenti

Risoluzione dei problemi

​Introduzione

​Iniziare

​Esempi di codice di trasformazione

​Payload del workflow di base

​Handler del workflow per gli abbonamenti

​Handler del workflow per le contestazioni

​Casi d’uso comuni di Windmill

​Suggerimenti

​Risoluzione dei problemi

Introduzione

Iniziare

Esempi di codice di trasformazione

Payload del workflow di base

Handler del workflow per gli abbonamenti

Handler del workflow per le contestazioni

Casi d’uso comuni di Windmill

Suggerimenti

Risoluzione dei problemi