Slack

はじめに

Slack integration は、成功した支払い、サブスクリプションの変更、異議申し立てなどの Dodo Payments イベントを、選択した Slack チャンネルに投稿します。チームはダッシュボードを確認しなくても、Slack から支払いを追跡し、異議申し立てに対応できます。

Slack connector は、各 Dodo Payments イベントを transformation によって Slack メッセージに変換します。transformation は、配信前にイベント上で実行される JavaScript コードです。connector には transformation code が付属しているため、開始時にコーディングは必要ありません。Dodo Payments dashboard の Developer → Webhooks へのアクセス権と、Slack workspace にアプリを追加する権限が必要です。

始め方

Open the Webhook Section

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

Add endpoint dialog with the Integration dropdown set to Custom webhook

Select Slack Integration

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

Add endpoint dialog with Slack selected and the How to connect Slack steps

Create a Slack Webhook URL

Slack で、通知を受け取るチャンネル用の incoming webhook を備えたアプリを作成します。

api.slack.com/apps を開き、Create New App をクリックして、From scratch を選択します。
アプリ名（例: Dodo Payments Notifications）を入力し、workspace を選択して Create App をクリックします。
サイドバーで Incoming Webhooks を開き、Activate Incoming Webhooks をオンにします。
Add New Webhook to Workspace をクリックし、チャンネルを選択して Allow をクリックします。
Webhook URL をコピーします。URL は https://hooks.slack.com/services/ で始まります。

Paste the Webhook URL

Slack webhook URL を Endpoint URL に貼り付けます。Slack に API key は必要ありません。

Select Events

Subscribed events には、Slack connector がサポートするイベントが一覧表示されます。transformation を変更する場合は、処理対象のイベントだけを残してください。Slack は Slack message ではないリクエストを拒否するため、transformation によって変更されないイベントは配信に失敗します。

Customize Transformation Code

Transformation code で handler を編集し、メッセージを投稿するイベントと各メッセージの形式を選択します。connector の code をそのまま使用するか、examples を基に開始します。

支払いイベント用の Slack handler が表示された Transformation code editor

Test and Create

Test this code でイベントタイプを選択し、Simulate をクリックします。Result に Slack が受信するメッセージが表示されます。次に Create endpoint をクリックします。

Test this code panel with payment.succeeded selected, a Simulate button, and the Create endpoint button

Integration Complete!

これで Dodo Payments は、購読した各イベントを Slack チャンネルに投稿します。テストメッセージを投稿するには、endpoint の Testing タブを開き、イベントタイプを選択して Send example をクリックします。

Transformation Code の例

各 handler は webhook.payload を Slack メッセージに置き換え、受信 webhook URL である webhook.url を保持します。Dodo Payments の金額は通貨の最小単位で表されるため、例では 100 で割り、通貨コードを表示しています。JPY や KRW などの小数点以下の桁がない通貨では、金額をそのまま使用してください。

基本的な Payment 通知

Payment が成功、失敗、または処理中になったときに、プレーンテキストのメッセージを投稿します。

payment_notifs.js

function handler(webhook) {
  switch (webhook.eventType) {
    case "payment.succeeded":
      webhook.payload = {
        text: `✅ Payment Successful\nAmount: ${(webhook.payload.data.total_amount / 100).toFixed(2)} ${webhook.payload.data.currency}\nCustomer: ${webhook.payload.data.customer.email}\nPayment ID: ${webhook.payload.data.payment_id}`
      };
      break;
      
    case "payment.failed":
      webhook.payload = {
        text: `❌ Payment Failed\nAmount: ${(webhook.payload.data.total_amount / 100).toFixed(2)} ${webhook.payload.data.currency}\nCustomer: ${webhook.payload.data.customer.email}\nReason: ${webhook.payload.data.error_message || 'Unknown'}`
      };
      break;
      
    case "payment.processing":
      webhook.payload = {
        text: `⏳ Payment Processing\nAmount: ${(webhook.payload.data.total_amount / 100).toFixed(2)} ${webhook.payload.data.currency}\nCustomer: ${webhook.payload.data.customer.email}`
      };
      break;
  }

  return webhook;
}

リッチな Subscription 通知

Subscription が有効化、キャンセル、または更新されたときに、attachment fields を含む色分けされたメッセージを投稿します。

subscription_notifs.js

function handler(webhook) {
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        attachments: [{
          color: "good",
          title: "🎉 Subscription Activated",
          fields: [
            {
              title: "Customer",
              value: webhook.payload.data.customer.email,
              short: true
            },
            {
              title: "Product ID",
              value: webhook.payload.data.product_id,
              short: true
            },
            {
              title: "Amount",
              value: `${(webhook.payload.data.recurring_pre_tax_amount / 100).toFixed(2)} ${webhook.payload.data.currency}/${webhook.payload.data.payment_frequency_interval}`,
              short: true
            },
            {
              title: "Next Billing",
              value: new Date(webhook.payload.data.next_billing_date).toLocaleDateString(),
              short: true
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "subscription.cancelled":
      webhook.payload = {
        attachments: [{
          color: "warning",
          title: "⚠️ Subscription Cancelled",
          fields: [
            {
              title: "Customer",
              value: webhook.payload.data.customer.email,
              short: true
            },
            {
              title: "Product ID",
              value: webhook.payload.data.product_id,
              short: true
            },
            {
              title: "Cancellation Date",
              value: new Date(webhook.payload.data.cancelled_at).toLocaleDateString(),
              short: true
            },
            {
              title: "Cancel at Next Billing",
              value: webhook.payload.data.cancel_at_next_billing_date ? "Yes" : "No",
              short: true
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "subscription.renewed":
      webhook.payload = {
        attachments: [{
          color: "good",
          title: "🔄 Subscription Renewed",
          fields: [
            {
              title: "Customer",
              value: webhook.payload.data.customer.email,
              short: true
            },
            {
              title: "Product ID",
              value: webhook.payload.data.product_id,
              short: true
            },
            {
              title: "Amount",
              value: `${(webhook.payload.data.recurring_pre_tax_amount / 100).toFixed(2)} ${webhook.payload.data.currency}`,
              short: true
            },
            {
              title: "Next Billing",
              value: new Date(webhook.payload.data.next_billing_date).toLocaleDateString(),
              short: true
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
  }

  return webhook;
}

Dispute 管理通知

Dispute が開始されたとき、または敗訴したときは赤いメッセージを、勝訴したときは緑のメッセージを投稿します。

dispute_notifs.js

function handler(webhook) {
  switch (webhook.eventType) {
    case "dispute.opened":
      webhook.payload = {
        attachments: [{
          color: "danger",
          title: "🚨 New Dispute Opened",
          fields: [
            {
              title: "Payment ID",
              value: webhook.payload.data.payment_id,
              short: true
            },
            {
              title: "Amount",
              value: `${(webhook.payload.data.amount / 100).toFixed(2)} ${webhook.payload.data.currency}`,
              short: true
            },
            {
              title: "Status",
              value: webhook.payload.data.dispute_status,
              short: true
            },
            {
              title: "Stage",
              value: webhook.payload.data.dispute_stage,
              short: true
            },
            {
              title: "Remarks",
              value: webhook.payload.data.remarks || "No remarks",
              short: false
            }
          ],
          footer: "Dodo Payments - Action Required",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "dispute.won":
      webhook.payload = {
        attachments: [{
          color: "good",
          title: "✅ Dispute Won",
          fields: [
            {
              title: "Payment ID",
              value: webhook.payload.data.payment_id,
              short: true
            },
            {
              title: "Amount",
              value: `${(webhook.payload.data.amount / 100).toFixed(2)} ${webhook.payload.data.currency}`,
              short: true
            },
            {
              title: "Status",
              value: webhook.payload.data.dispute_status,
              short: true
            },
            {
              title: "Resolution",
              value: "Dispute resolved in your favor",
              short: false
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "dispute.lost":
      webhook.payload = {
        attachments: [{
          color: "danger",
          title: "❌ Dispute Lost",
          fields: [
            {
              title: "Payment ID",
              value: webhook.payload.data.payment_id,
              short: true
            },
            {
              title: "Amount",
              value: `${(webhook.payload.data.amount / 100).toFixed(2)} ${webhook.payload.data.currency}`,
              short: true
            },
            {
              title: "Status",
              value: webhook.payload.data.dispute_status,
              short: true
            },
            {
              title: "Impact",
              value: "The disputed amount stays deducted from your balance",
              short: false
            }
          ],
          footer: "Dodo Payments - Review Required",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
  }

  return webhook;
}

すべてのイベントに対応する包括的な handler

すべてのイベントタイプで同じ形式のメッセージを投稿します。独自の case を持たないイベントには、イベントタイプと時刻を含む汎用メッセージが使用されます。

all_events_notifs.js

function handler(webhook) {
  const event = webhook.payload.data;
  const timestamp = new Date(webhook.payload.timestamp).toLocaleString();
  
  let color, emoji, title, fields = [];
  
  switch (webhook.eventType) {
    case "payment.succeeded":
      color = "good";
      emoji = "✅";
      title = "Payment Successful";
      fields = [
        { title: "Amount", value: `${(event.total_amount / 100).toFixed(2)} ${event.currency}`, short: true },
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Payment ID", value: event.payment_id, short: true },
        { title: "Method", value: event.payment_method || "Unknown", short: true }
      ];
      break;
      
    case "payment.failed":
      color = "danger";
      emoji = "❌";
      title = "Payment Failed";
      fields = [
        { title: "Amount", value: `${(event.total_amount / 100).toFixed(2)} ${event.currency}`, short: true },
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Reason", value: event.error_message || "Unknown", short: false }
      ];
      break;
      
    case "subscription.active":
      color = "good";
      emoji = "🎉";
      title = "Subscription Activated";
      fields = [
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Product ID", value: event.product_id, short: true },
        { title: "Amount", value: `${(event.recurring_pre_tax_amount / 100).toFixed(2)} ${event.currency}/${event.payment_frequency_interval}`, short: true },
        { title: "Next Billing", value: new Date(event.next_billing_date).toLocaleDateString(), short: true }
      ];
      break;
      
    case "subscription.cancelled":
      color = "warning";
      emoji = "⚠️";
      title = "Subscription Cancelled";
      fields = [
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Product ID", value: event.product_id, short: true },
        { title: "Cancellation Date", value: new Date(event.cancelled_at).toLocaleDateString(), short: true },
        { title: "Cancel at Next Billing", value: event.cancel_at_next_billing_date ? "Yes" : "No", short: true }
      ];
      break;
      
    case "refund.succeeded":
      color = "good";
      emoji = "💰";
      title = "Refund Processed";
      fields = [
        { title: "Amount", value: `${(event.amount / 100).toFixed(2)} ${event.currency || ""}`, short: true },
        { title: "Refund ID", value: event.refund_id, short: true },
        { title: "Payment ID", value: event.payment_id, short: true },
        { title: "Reason", value: event.reason || "Not specified", short: true }
      ];
      break;
      
    case "dispute.opened":
      color = "danger";
      emoji = "🚨";
      title = "New Dispute Opened";
      fields = [
        { title: "Payment ID", value: event.payment_id, short: true },
        { title: "Amount", value: `${(event.amount / 100).toFixed(2)} ${event.currency}`, short: true },
        { title: "Status", value: event.dispute_status, short: true },
        { title: "Stage", value: event.dispute_stage, short: true },
        { title: "Remarks", value: event.remarks || "No remarks", short: false }
      ];
      break;
      
    case "license_key.created":
      color = "good";
      emoji = "🔑";
      title = "License Key Created";
      fields = [
        { title: "License ID", value: event.id, short: true },
        { title: "Product ID", value: event.product_id, short: true },
        { title: "License Key", value: event.key.substring(0, 8) + "****", short: true },
        { title: "Expires", value: event.expires_at ? new Date(event.expires_at).toLocaleDateString() : "Never", short: true }
      ];
      break;
      
    default:
      // Handle any other events with a generic format
      color = "#3aa3e3";
      emoji = "ℹ️";
      title = webhook.eventType.replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
      fields = [
        { title: "Event Type", value: webhook.eventType, short: true },
        { title: "Timestamp", value: timestamp, short: true }
      ];
  }
  
  webhook.payload = {
    attachments: [{
      color: color,
      title: `${emoji} ${title}`,
      fields: fields,
      footer: "Dodo Payments",
      ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
    }]
  };

  return webhook;
}

ベストプラクティス

Slack 通知を有用なものに保つため、次のプラクティスに従ってください。

各イベントを明確にし、対応しやすくするため、色と fields を含む message attachments を使用します。
チームがレコードをすばやく見つけられるよう、金額、customer email、ID などの重要なデータを含めます。
イベントタイプに合わせて色を設定します。成功には緑（good）、dispute または失敗には赤（danger）、キャンセルには黄色（warning）、情報イベントには青（#3aa3e3）を使用します。
timestamp（ts）を追加し、各メッセージにイベントが発生した時刻を表示します。

機密データを扱う: full license keys や個人データなどの機密性の高い値を Slack に投稿しないでください。all-events の例の license key field のように、値を切り詰めるかマスクしてください。

トラブルシューティング

Notifications Not Appearing in Slack

Slack webhook URL が正しく、対応する Slack app が引き続きインストールされていることを確認します。
transformation code が有効な JavaScript であることを確認します。
購読しているイベントが発生していることを確認します。イベントを送信するには、endpoint の Testing タブで Send example を使用します。
Slack app で Incoming Webhooks が有効になっており、channel に投稿できることを確認します。

Transformation Errors

Developer → Webhooks の Logs タブを開き、失敗した delivery の response を確認します。
code が読み取る payload fields が、そのイベントタイプの event payload と一致していることを確認します。
Simulate と sample payload を使用して code をテストします。
code が読み取る各 field が存在することを確認します。error_message などの optional fields は、null にできます。

Missing Event Types

Subscribed events でイベントが選択されていることを確認します。選択を変更するには、endpoint を開いて Edit をクリックします。
Slack connector がイベントをサポートしていることを確認します。Subscribed events には、connector がサポートするイベントのみが一覧表示されます。
transformation にそのイベント用の case があることを確認します。例では他のイベントを変更せずに残しているため、Slack に拒否されます。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

はじめに

始め方

Transformation Code の例

基本的な Payment 通知

リッチな Subscription 通知

Dispute 管理通知

すべてのイベントに対応する包括的な handler

ベストプラクティス

トラブルシューティング