Windmill

Introdução

Execute um script ou flow do Windmill sempre que ocorrer um evento do Dodo Payments. Use-o para atualizar um banco de dados, sincronizar registros com outro sistema, enviar notificações ou executar sua própria lógica de negócios em código.

O conector do Windmill envia cada evento para a URL de webhook de um script ou flow do Windmill. Você precisa de um script ou flow implantado, um token do Windmill que possa executá-lo e acesso a Developer → Webhooks no dashboard do Dodo Payments.

Começando

Open the Webhook Section

No dashboard do Dodo Payments, acesse Developer → Webhooks e clique em Add endpoint.

Caixa de diálogo Add endpoint com Windmill selecionado no menu suspenso Integration e as etapas How to connect Windmill

Select Windmill

Em Integration, selecione Windmill. O dashboard carrega o código de transformação do Windmill e mostra as etapas de configuração no painel How to connect Windmill.

Copy the Windmill Webhook URL

No Windmill, abra o script ou flow que deve processar os eventos. Na aba Triggers, abra Webhooks e copie a URL de webhook assíncrona (UUID/Async). Em seguida, crie um token específico de webhook para o script ou flow e copie-o. Esse token pode executar apenas esse script ou flow.

Paste Webhook URL

Cole a URL de webhook do Windmill em Endpoint URL. A URL deve usar HTTPS, portanto uma instância do Windmill hospedada por você precisa de um endereço HTTPS público. O conector do Windmill não tem um campo de API key, então você adicionará o token depois de criar o endpoint.

Select Events

Subscribed events lista os eventos compatíveis com o conector do Windmill. Mantenha apenas os eventos processados pelo seu script ou flow.

Configure Transformation

Em Transformation code, edite o handler para que as chaves de nível superior do payload correspondam às entradas do seu script ou flow. Comece pelos exemplos.

Test & Create

Em Test this code, selecione um tipo de evento e clique em Simulate para visualizar o payload. Em seguida, clique em Create endpoint.

Add the Windmill Token

Logo depois de criar o endpoint, abra a aba Advanced. Em Custom headers, clique em Add header. Insira Authorization como nome e Bearer, um espaço e seu token como valor. Em seguida, clique em Save. Até que você salve o header, o Windmill rejeita as entregas, e o Dodo Payments tenta enviá-las novamente de acordo com o cronograma de tentativas.O Windmill também aceita o token em um parâmetro de consulta token no final da URL. O Windmill recomenda o header, pois qualquer pessoa que consiga ver uma URL com um token pode usar o token.

Done

Os eventos inscritos agora iniciam execuções do seu script ou flow. Para enviar um evento de teste, abra a aba Testing do endpoint, selecione um tipo de evento e clique em Send example. No Windmill, a execução aparece na página Runs com o trigger Webhook.

Exemplos de código de transformação

Cada handler substitui webhook.payload por um objeto plano e mantém webhook.url, sua URL de webhook do Windmill. O Windmill envia cada chave de nível superior para a entrada do script ou flow com o mesmo nome, portanto um script para o primeiro exemplo declara entradas como event_type, payment_id e amount. Os valores monetários do Dodo Payments estão na menor unidade da moeda, então os exemplos dividem o valor por 100 e enviam o resultado como uma string, como "25.00". Para moedas sem casas decimais, como JPY e KRW, use o valor como está.

Payload de workflow básico

Envie os detalhes de um pagamento bem-sucedido:

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 assinatura

Envie um evento subscription_started ou subscription_cancelled quando uma assinatura se tornar ativa ou for cancelada:

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 disputa

Envie todos os eventos de disputa, com urgent definido como true quando uma disputa for aberta:

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 comuns do Windmill

Database Operations

Atualizar registros de clientes no PostgreSQL ou MySQL
Registrar eventos de pagamento em um data warehouse
Sincronizar dados com sistemas externos
Atualizar níveis de estoque
Acompanhar métricas de analytics

Business Logic

Calcular métricas de receita
Processar reembolsos e ajustes
Processar alterações no ciclo de vida de assinaturas
Gerar relatórios e exportações
Validar dados de pagamento

External Integrations

Enviar dados para plataformas de analytics
Atualizar sistemas de CRM
Iniciar campanhas de e-mail
Criar eventos de calendário
Enviar notificações por SMS

Dicas

Dê às chaves do payload o mesmo nome das entradas do seu script ou flow, pois o Windmill mapeia cada chave de nível superior para a entrada com o mesmo nome.
Use os mesmos nomes de campos em todos os eventos, para que um único script possa processar vários tipos de evento.
Inclua o tipo de evento e timestamp. Os eventos podem chegar fora de ordem, e timestamp permite que seu script os ordene.
Use a URL de webhook assíncrona. A URL síncrona aguarda a conclusão da execução, e uma execução que ultrapasse o tempo limite da entrega é considerada uma entrega com falha, que o Dodo Payments tenta enviar novamente.
Faça com que seu script possa ser executado duas vezes com segurança para o mesmo evento, pois as tentativas podem entregar um evento mais de uma vez.
Para ignorar um evento no código, defina webhook.cancel = true antes de retornar o webhook. Os logs registram uma entrega ignorada como bem-sucedida.
Use os handlers de erro do Windmill para receber notificações quando uma execução falhar.

Solução de problemas

Workflows Not Triggering

Verifique se Endpoint URL é a URL de webhook do seu script ou flow e se o endpoint está habilitado.
Verifique se o header Authorization contém Bearer e um token válido. Um token específico de webhook executa apenas o próprio script ou flow.
Verifique se o script ou flow está implantado. O webhook executa a versão implantada mais recente, não um rascunho.
Abra a aba Logs em Developer → Webhooks para ver a resposta do Windmill a cada entrega.

Data Processing Issues

Verifique se as chaves de nível superior do payload correspondem às entradas do script ou flow pelo nome.
Verifique se cada valor corresponde ao tipo da entrada. Os exemplos enviam valores monetários como strings.
Verifique a execução na página Runs do Windmill, filtrando pelo trigger Webhook. A URL assíncrona responde assim que o Windmill coloca a execução na fila, portanto os logs do Dodo Payments mostram uma entrega bem-sucedida mesmo quando a execução falha.
Execute o script ou flow no Windmill com um payload de Simulate.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introdução

Começando

Exemplos de código de transformação

Payload de workflow básico

Handler de workflow de assinatura

Handler de workflow de disputa

Casos de uso comuns do Windmill

Dicas

Solução de problemas

​Introdução

​Começando

​Exemplos de código de transformação

​Payload de workflow básico

​Handler de workflow de assinatura

​Handler de workflow de disputa

​Casos de uso comuns do Windmill

​Dicas

​Solução de problemas

Introdução

Começando

Exemplos de código de transformação

Payload de workflow básico

Handler de workflow de assinatura

Handler de workflow de disputa

Casos de uso comuns do Windmill

Dicas

Solução de problemas