Cối xay gió

Giới thiệu

Chạy một script hoặc flow của Windmill mỗi khi xảy ra sự kiện Dodo Payments. Sử dụng để cập nhật cơ sở dữ liệu, đồng bộ bản ghi với hệ thống khác, gửi thông báo hoặc chạy logic nghiệp vụ của riêng bạn bằng mã.

Connector Windmill gửi mỗi sự kiện đến URL webhook của một script hoặc flow Windmill. Bạn cần một script hoặc flow đã được triển khai, một token Windmill có thể chạy script hoặc flow đó và quyền truy cập Developer → Webhooks trong dashboard Dodo Payments.

Bắt đầu

Open the Webhook Section

Trong bảng điều khiển Dodo Payments, chuyển đến Developer → Webhooks và nhấp vào Add endpoint.

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

Select Windmill

Trong Integration, chọn Windmill. Dashboard sẽ tải mã chuyển đổi Windmill và hiển thị các bước thiết lập trong bảng How to connect Windmill.

Copy the Windmill Webhook URL

Trong Windmill, mở script hoặc flow sẽ xử lý các sự kiện. Trên tab Triggers, mở Webhooks và sao chép URL webhook không đồng bộ (UUID/Async). Sau đó tạo token dành riêng cho webhook của script hoặc flow và sao chép token đó. Token này chỉ có thể chạy script hoặc flow đó.

Paste Webhook URL

Dán URL webhook Windmill vào Endpoint URL. URL phải sử dụng HTTPS, vì vậy một instance Windmill tự lưu trữ cần có địa chỉ HTTPS công khai. Connector Windmill không có trường API key, nên bạn sẽ thêm token sau khi tạo endpoint.

Select Events

Subscribed events liệt kê các sự kiện được connector Windmill hỗ trợ. Chỉ giữ lại những sự kiện mà script hoặc flow của bạn xử lý.

Configure Transformation

Trong Transformation code, chỉnh sửa handler để các key cấp cao nhất của payload khớp với các input của script hoặc flow. Bắt đầu từ các ví dụ.

Test & Create

Trong Test this code, chọn một loại sự kiện và nhấp vào Simulate để xem trước payload. Sau đó nhấp vào Create endpoint.

Add the Windmill Token

Ngay sau khi tạo endpoint, mở tab Advanced. Trong Custom headers, nhấp vào Add header. Nhập Authorization làm tên, còn Bearer, một dấu cách và token của bạn làm giá trị. Sau đó nhấp vào Save. Cho đến khi bạn lưu header, Windmill sẽ từ chối các lần gửi và Dodo Payments sẽ thử lại theo lịch thử lại.Windmill cũng chấp nhận token trong query parameter token ở cuối URL. Windmill khuyến nghị sử dụng header, vì bất kỳ ai nhìn thấy URL có token đều có thể sử dụng token đó.

Done

Các sự kiện đã đăng ký giờ đây sẽ bắt đầu các lần chạy của script hoặc flow. Để gửi một sự kiện kiểm thử, mở tab Testing của endpoint, chọn loại sự kiện và nhấp vào Send example. Trong Windmill, lần chạy sẽ xuất hiện trên trang Runs với trigger Webhook.

Ví dụ về mã chuyển đổi

Mỗi handler thay thế webhook.payload bằng một object phẳng và giữ lại webhook.url, URL webhook Windmill của bạn. Windmill truyền từng key cấp cao nhất vào input của script hoặc flow có cùng tên, vì vậy script cho ví dụ đầu tiên sẽ khai báo các input như event_type, payment_id và amount. Số tiền Dodo Payments được biểu thị bằng đơn vị tiền tệ nhỏ nhất, vì vậy các ví dụ chia cho 100 và gửi kết quả dưới dạng chuỗi, chẳng hạn như "25.00". Đối với các loại tiền tệ không có chữ số thập phân như JPY và KRW, hãy sử dụng nguyên giá trị số tiền.

Payload cho workflow cơ bản

Gửi thông tin chi tiết của một khoản thanh toán thành công:

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 cho workflow subscription

Gửi sự kiện subscription_started hoặc subscription_cancelled khi một subscription được kích hoạt hoặc bị hủy:

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 cho workflow dispute

Gửi mọi sự kiện dispute, với urgent được đặt thành true khi dispute được mở:

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

Các trường hợp sử dụng Windmill phổ biến

Database Operations

Cập nhật bản ghi customer trong PostgreSQL hoặc MySQL
Ghi nhật ký các sự kiện thanh toán vào data warehouse
Đồng bộ dữ liệu với các hệ thống bên ngoài
Cập nhật mức tồn kho
Theo dõi các metric analytics

Business Logic

Tính toán các metric doanh thu
Xử lý refund và các khoản điều chỉnh
Xử lý các thay đổi trong vòng đời subscription
Tạo báo cáo và bản export
Xác thực dữ liệu thanh toán

External Integrations

Gửi dữ liệu đến các nền tảng analytics
Cập nhật các hệ thống CRM
Bắt đầu các chiến dịch email
Tạo sự kiện lịch
Gửi thông báo SMS

Mẹo

Đặt tên các key của payload theo input của script hoặc flow, vì Windmill ánh xạ từng key cấp cao nhất vào input có cùng tên.
Sử dụng cùng tên field giữa các sự kiện để một script có thể xử lý nhiều loại sự kiện.
Bao gồm loại sự kiện và timestamp. Các sự kiện có thể đến không theo thứ tự và timestamp cho phép script sắp xếp chúng.
Sử dụng URL webhook không đồng bộ. URL đồng bộ sẽ chờ lần chạy hoàn tất; nếu lần chạy kéo dài quá timeout của lần gửi thì lần gửi đó được tính là thất bại và Dodo Payments sẽ thử lại.
Đảm bảo script có thể chạy an toàn hai lần cho cùng một sự kiện, vì các lần thử lại có thể gửi một sự kiện nhiều hơn một lần.
Để bỏ qua một sự kiện trong code, đặt webhook.cancel = true trước khi return webhook. Logs ghi nhận lần gửi bị bỏ qua là thành công.
Sử dụng error handlers của Windmill để nhận thông báo khi một lần chạy thất bại.

Khắc phục sự cố

Workflows Not Triggering

Kiểm tra để đảm bảo Endpoint URL là URL webhook của script hoặc flow và endpoint đã được bật.
Kiểm tra header Authorization chứa Bearer và token hợp lệ. Token dành riêng cho webhook chỉ chạy script hoặc flow tương ứng.
Kiểm tra script hoặc flow đã được triển khai. Webhook chạy phiên bản được triển khai mới nhất, không phải bản draft.
Mở tab Logs trong Developer → Webhooks để xem phản hồi của Windmill cho từng lần gửi.

Data Processing Issues

Kiểm tra để đảm bảo các key cấp cao nhất của payload khớp theo tên với input của script hoặc flow.
Kiểm tra để đảm bảo mỗi giá trị khớp với kiểu input tương ứng. Các ví dụ gửi số tiền dưới dạng chuỗi.
Kiểm tra lần chạy trên trang Runs của Windmill, được lọc theo trigger Webhook. URL không đồng bộ phản hồi ngay khi Windmill xếp hàng lần chạy, vì vậy logs Dodo Payments hiển thị lần gửi thành công ngay cả khi lần chạy thất bại.
Chạy script hoặc flow trong Windmill với payload từ Simulate.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Giới thiệu

Bắt đầu

Ví dụ về mã chuyển đổi

Payload cho workflow cơ bản

Handler cho workflow subscription

Handler cho workflow dispute

Các trường hợp sử dụng Windmill phổ biến

Mẹo

Khắc phục sự cố

​Giới thiệu

​Bắt đầu

​Ví dụ về mã chuyển đổi

​Payload cho workflow cơ bản

​Handler cho workflow subscription

​Handler cho workflow dispute

​Các trường hợp sử dụng Windmill phổ biến

​Mẹo

​Khắc phục sự cố

Giới thiệu

Bắt đầu

Ví dụ về mã chuyển đổi

Payload cho workflow cơ bản

Handler cho workflow subscription

Handler cho workflow dispute

Các trường hợp sử dụng Windmill phổ biến

Mẹo

Khắc phục sự cố