ウィンドミル

はじめに

Dodo Paymentsイベントが発生するたびにWindmillスクリプトまたはフローを実行します。データベースの更新、別のシステムへのレコード同期、通知の送信、コードによる独自のビジネスロジックの実行などに利用できます。

Windmill connectorは、各イベントをWindmillスクリプトまたはフローのwebhook URLに送信します。デプロイ済みのスクリプトまたはフロー、それを実行できるWindmill token、そしてDodo PaymentsダッシュボードのDeveloper → Webhooksへのアクセスが必要です。

はじめに

Open the Webhook Section

Dodo Payments ダッシュボードで、Developer → Webhooks に移動し、Add endpoint をクリックします。

Add endpoint ダイアログで、Integration ドロップダウンから Windmill が選択され、Windmill の接続方法の手順が表示されている状態

Select Windmill

IntegrationでWindmillを選択します。ダッシュボードにWindmill transformation codeが読み込まれ、How to connect Windmillパネルにセットアップ手順が表示されます。

Copy the Windmill Webhook URL

Windmillで、イベントを処理するスクリプトまたはフローを開きます。そのTriggersタブでWebhooksを開き、非同期（UUID/Async）webhook URLをコピーします。次に、そのスクリプトまたはフロー専用のtokenを作成してコピーします。このtokenで実行できるのは、そのスクリプトまたはフローだけです。

Paste Webhook URL

Windmill webhook URLをEndpoint URLに貼り付けます。URLはHTTPSを使用する必要があるため、self-hosted Windmill instanceには公開HTTPSアドレスが必要です。Windmill connectorにはAPI key fieldがないため、endpointを作成した後にtokenを追加します。

Select Events

Subscribed eventsには、Windmill connectorがサポートするイベントが一覧表示されます。スクリプトまたはフローが処理するイベントだけを残します。

Configure Transformation

Transformation codeでhandlerを編集し、payloadのtop-level keysがスクリプトまたはフローのinputsと一致するようにします。examplesを参考にしてください。

Test & Create

Test this codeでイベントタイプを選択し、Simulateをクリックしてpayloadをプレビューします。次にCreate endpointをクリックします。

Add the Windmill Token

endpointを作成した直後に、そのAdvancedタブを開きます。Custom headersでAdd headerをクリックします。名前にAuthorizationを入力し、値にBearer、スペース、そしてtokenを入力します。次にSaveをクリックします。headerを保存するまでWindmillはdeliveryを拒否し、Dodo Paymentsはretry scheduleに従って再試行します。Windmillは、URL末尾のtoken query parameterでもtokenを受け付けます。ただし、token付きURLを閲覧できる人は誰でもtokenを使用できるため、Windmillはheaderを推奨しています。

Done

これでSubscribed eventsによってスクリプトまたはフローのrunが開始されます。テストイベントを送信するには、endpointのTestingタブを開き、イベントタイプを選択してSend exampleをクリックします。Windmillでは、runがWebhook triggerとともにRunsページに表示されます。

Transformation Codeの例

各handlerはwebhook.payloadをflat objectに置き換え、Windmill webhook URLであるwebhook.urlを保持します。Windmillは各top-level keyを、同じ名前のスクリプトまたはフローのinputに渡します。そのため、最初の例のスクリプトでは、event_type、payment_id、amountなどのinputsを宣言します。Dodo Paymentsのamountsは通貨の最小単位で表されるため、例では100で割り、"25.00"のように結果をstringとして送信します。JPYやKRWなどの小数点以下0桁の通貨では、amountをそのまま使用します。

Basic Workflow Payload

成功したpaymentの詳細を送信します。

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

Subscription Workflow Handler

subscriptionがactiveになったとき、またはcancelledになったときに、subscription_startedまたはsubscription_cancelled eventを送信します。

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

Dispute Workflow Handler

すべてのdispute eventを送信します。disputeが開始されたときはurgentをtrueに設定します。

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

Windmillの一般的なユースケース

Database Operations

PostgreSQLまたはMySQLのcustomer recordsを更新する
payment eventsをdata warehouseに記録する
external systemsにdataを同期する
inventory levelsを更新する
analytics metricsを追跡する

Business Logic

revenue metricsを計算する
refundsとadjustmentsを処理する
subscription lifecycle changesに対応する
reportsとexportsを生成する
payment dataを検証する

External Integrations

analytics platformsにdataを送信する
CRM systemsを更新する
email campaignsを開始する
calendar eventsを作成する
SMS notificationsを送信する

ヒント

payload keysにはスクリプトまたはフローのinputsの名前を付けます。Windmillは各top-level keyを、同じ名前のinputにマッピングします。
複数のevent typesを1つのスクリプトで処理できるよう、イベント間で同じfield namesを使用します。
event typeとtimestampを含めます。イベントは順不同で届く可能性があり、timestampによってスクリプトで順序付けできます。
非同期webhook URLを使用します。同期URLはrunが完了するまで待機するため、delivery timeoutを超えたrunはfailed deliveryとして扱われ、Dodo Paymentsによって再試行されます。
同じeventに対してスクリプトが2回実行されても安全なようにします。retryによって、eventが複数回deliveryされる可能性があります。
codeでeventをスキップするには、webhookをreturnする前にwebhook.cancel = trueを設定します。logsでは、スキップされたdeliveryがsuccessfulとして記録されます。
Windmillのerror handlersを使用して、runが失敗したときに通知を受け取ります。

トラブルシューティング

Workflows Not Triggering

Endpoint URLがスクリプトまたはフローのwebhook URLであり、endpointが有効になっていることを確認します。
Authorization headerにBearerと有効なtokenが含まれていることを確認します。webhook-specific tokenで実行できるのは、そのtokenに対応するスクリプトまたはフローだけです。
スクリプトまたはフローがデプロイ済みであることを確認します。webhookはdraftではなく、最後にデプロイされたversionを実行します。
Developer → WebhooksのLogsタブを開き、各deliveryに対するWindmillのresponseを確認します。

Data Processing Issues

payloadのtop-level keysが、名前によってスクリプトまたはフローのinputsと一致していることを確認します。
各valueがinput typeと一致していることを確認します。例ではamountsをstringsとして送信します。
Webhook triggerでフィルタリングした、WindmillのRunsページでrunを確認します。非同期URLはWindmillがrunをqueueに入れるとすぐにresponseを返すため、runが失敗してもDodo Payments logsではsuccessful deliveryと表示されます。
Simulateのpayloadを使って、Windmillでスクリプトまたはフローを実行します。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

はじめに

はじめに

Transformation Codeの例

Basic Workflow Payload

Subscription Workflow Handler

Dispute Workflow Handler

Windmillの一般的なユースケース

ヒント

トラブルシューティング

​はじめに

​はじめに

​Transformation Codeの例

​Basic Workflow Payload

​Subscription Workflow Handler

​Dispute Workflow Handler

​Windmillの一般的なユースケース

​ヒント

​トラブルシューティング

はじめに

はじめに

Transformation Codeの例

Basic Workflow Payload

Subscription Workflow Handler

Dispute Workflow Handler

Windmillの一般的なユースケース

ヒント

トラブルシューティング