Windmill

Introducción

Ejecuta un script o flow de Windmill cada vez que ocurra un evento de Dodo Payments. Úsalo para actualizar una base de datos, sincronizar registros con otro sistema, enviar notificaciones o ejecutar tu propia lógica empresarial en código.

El conector de Windmill envía cada evento a la URL de webhook de un script o flow de Windmill. Necesitas un script o flow implementado, un token de Windmill que pueda ejecutarlo y acceso a Developer → Webhooks en el dashboard de Dodo Payments.

Comenzando

Open the Webhook Section

En el panel de Dodo Payments, ve a Developer → Webhooks y haz clic en Add endpoint.

Add endpoint dialog with Windmill selected in the Integration dropdown and the How to connect Windmill steps

Select Windmill

En Integration, selecciona Windmill. El dashboard carga el código de transformación de Windmill y muestra los pasos de configuración en el panel How to connect Windmill.

Copy the Windmill Webhook URL

En Windmill, abre el script o flow que debe gestionar los eventos. En su pestaña Triggers, abre Webhooks y copia la URL de webhook asíncrona (UUID/Async). Después, crea un token específico del webhook para el script o flow y cópialo. Este token solo puede ejecutar ese script o flow.

Paste Webhook URL

Pega la URL de webhook de Windmill en Endpoint URL. La URL debe usar HTTPS, por lo que una instancia de Windmill self-hosted necesita una dirección HTTPS pública. El conector de Windmill no tiene un campo de API key, así que debes añadir el token después de crear el endpoint.

Select Events

Subscribed events muestra los eventos compatibles con el conector de Windmill. Conserva únicamente los eventos que gestione tu script o flow.

Configure Transformation

En Transformation code, edita el handler para que las claves del nivel superior del payload coincidan con las entradas de tu script o flow. Empieza con los ejemplos.

Test & Create

En Test this code, selecciona un tipo de evento y haz clic en Simulate para previsualizar el payload. Después, haz clic en Create endpoint.

Add the Windmill Token

Justo después de crear el endpoint, abre su pestaña Advanced. En Custom headers, haz clic en Add header. Introduce Authorization como nombre y Bearer, un espacio y tu token como valor. Después, haz clic en Save. Hasta que guardes el header, Windmill rechaza las entregas y Dodo Payments las reintenta según el calendario de reintentos.Windmill también acepta el token en un parámetro de consulta token al final de la URL. Windmill recomienda usar el header, porque cualquiera que pueda ver una URL con un token puede utilizarlo.

Done

Los eventos suscritos ahora inician ejecuciones de tu script o flow. Para enviar un evento de prueba, abre la pestaña Testing del endpoint, selecciona un tipo de evento y haz clic en Send example. En Windmill, la ejecución aparece en la página Runs con el trigger Webhook.

Ejemplos de código de transformación

Cada handler reemplaza webhook.payload con un objeto plano y conserva webhook.url, la URL de webhook de Windmill. Windmill pasa cada clave del nivel superior a la entrada del script o flow con el mismo nombre, por lo que un script para el primer ejemplo declara entradas como event_type, payment_id y amount. Los importes de Dodo Payments están expresados en la unidad monetaria más pequeña, por lo que los ejemplos dividen entre 100 y envían el resultado como una cadena, como "25.00". Para monedas sin decimales, como JPY y KRW, utiliza el importe tal cual.

Payload de workflow básico

Envía los detalles de un pago exitoso:

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 de workflow de suscripción

Envía un evento subscription_started o subscription_cancelled cuando una suscripción se active o se cancele:

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 de workflow de disputas

Envía cada evento de disputa, con urgent establecido en true cuando se abre una disputa:

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

Casos de uso habituales de Windmill

Database Operations

Actualizar registros de clientes en PostgreSQL o MySQL
Registrar eventos de pago en un data warehouse
Sincronizar datos con sistemas externos
Actualizar niveles de inventario
Realizar un seguimiento de métricas de analítica

Business Logic

Calcular métricas de ingresos
Procesar reembolsos y ajustes
Gestionar cambios en el ciclo de vida de las suscripciones
Generar informes y exportaciones
Validar datos de pago

External Integrations

Enviar datos a plataformas de analítica
Actualizar sistemas de CRM
Iniciar campañas de correo electrónico
Crear eventos de calendario
Enviar notificaciones por SMS

Consejos

Asigna nombres a las claves del payload según las entradas de tu script o flow, porque Windmill asigna cada clave del nivel superior a la entrada con el mismo nombre.
Utiliza los mismos nombres de campo en todos los eventos para que un script pueda gestionar varios tipos de evento.
Incluye el tipo de evento y timestamp. Los eventos pueden llegar desordenados, y timestamp permite que tu script los ordene.
Utiliza la URL de webhook asíncrona. La URL síncrona espera a que termine la ejecución, y una ejecución que supere el timeout de entrega se considera una entrega fallida, que Dodo Payments reintenta.
Haz que tu script pueda ejecutarse dos veces de forma segura para el mismo evento, ya que los reintentos pueden entregar un evento más de una vez.
Para omitir un evento en el código, establece webhook.cancel = true antes de devolver el webhook. Los logs registran una entrega omitida como exitosa.
Utiliza los handlers de errores de Windmill para recibir notificaciones cuando falle una ejecución.

Solución de problemas

Workflows Not Triggering

Comprueba que Endpoint URL sea la URL de webhook de tu script o flow y que el endpoint esté habilitado.
Comprueba que el header Authorization contenga Bearer y un token válido. Un token específico del webhook solo ejecuta su propio script o flow.
Comprueba que el script o flow esté implementado. El webhook ejecuta la última versión implementada, no un borrador.
Abre la pestaña Logs en Developer → Webhooks para ver la respuesta de Windmill a cada entrega.

Data Processing Issues

Comprueba que las claves del nivel superior del payload coincidan por nombre con las entradas del script o flow.
Comprueba que cada valor coincida con el tipo de su entrada. Los ejemplos envían los importes como cadenas.
Comprueba la ejecución en la página Runs de Windmill, filtrada por el trigger Webhook. La URL asíncrona responde en cuanto Windmill pone en cola la ejecución, por lo que los logs de Dodo Payments muestran una entrega exitosa incluso si la ejecución falla.
Ejecuta el script o flow en Windmill con un payload de Simulate.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introducción

Comenzando

Ejemplos de código de transformación

Payload de workflow básico

Handler de workflow de suscripción

Handler de workflow de disputas

Casos de uso habituales de Windmill

Consejos

Solución de problemas

​Introducción

​Comenzando

​Ejemplos de código de transformación

​Payload de workflow básico

​Handler de workflow de suscripción

​Handler de workflow de disputas

​Casos de uso habituales de Windmill

​Consejos

​Solución de problemas

Introducción

Comenzando

Ejemplos de código de transformación

Payload de workflow básico

Handler de workflow de suscripción

Handler de workflow de disputas

Casos de uso habituales de Windmill

Consejos

Solución de problemas