Slack

المقدمة

يُرسل تكامل Slack أحداث Dodo Payments، مثل payments الناجحة وتغييرات الاشتراكات والنزاعات، إلى قناة Slack تختارها. يمكن لفريقك متابعة payments والتعامل مع النزاعات من Slack، من دون التحقق من لوحة التحكم.

يحوّل موصل Slack كل حدث من Dodo Payments إلى رسالة Slack من خلال transformation: كود JavaScript يعمل على الحدث قبل تسليمه. يأتي الموصل مزودًا بكود transformation، لذلك لا تحتاج إلى كتابة كود للبدء. تحتاج إلى الوصول إلى Developer → Webhooks في لوحة تحكم Dodo Payments، وإلى صلاحية إضافة تطبيقات إلى مساحة عمل Slack الخاصة بك.

البدء

Open the Webhook Section

في لوحة تحكم Dodo Payments، انتقل إلى Developer → Webhooks وانقر على Add endpoint.

مربع حوار Add endpoint مع ضبط القائمة المنسدلة Integration على Custom webhook

Select Slack Integration

ضمن Integration، اختر Slack. تحمّل لوحة التحكم رمز التحويل الخاص بـ Slack وتعرض خطوات الإعداد في لوحة How to connect Slack.

مربع حوار Add endpoint مع اختيار Slack وخطوات How to connect Slack

Create a Slack Webhook URL

في Slack، أنشئ تطبيقًا يتضمن incoming webhook للقناة التي يجب أن تتلقى الإشعارات:

افتح api.slack.com/apps، وانقر على Create New App، ثم اختر From scratch.
سمِّ التطبيق، على سبيل المثال Dodo Payments Notifications، واختر مساحة عملك، ثم انقر على Create App.
من الشريط الجانبي، افتح Incoming Webhooks وفعّل Activate Incoming Webhooks.
انقر على Add New Webhook to Workspace، واختر القناة، ثم انقر على Allow.
انسخ Webhook URL الذي يبدأ بـ https://hooks.slack.com/services/.

شاشة أذونات Slack تتضمن محدد قناة وزر Allow

Paste the Webhook URL

الصق عنوان Slack webhook URL في Endpoint URL. لا يحتاج Slack إلى API key.

Select Events

تعرض Subscribed events الأحداث التي يدعمها موصل Slack. إذا غيّرت transformation، احتفظ فقط بالأحداث التي يعالجها. يرفض Slack الطلب الذي لا يمثل رسالة Slack، ولذلك يفشل تسليم الحدث الذي تتركه transformation من دون تغيير.

Customize Transformation Code

ضمن Transformation code، عدّل handler لاختيار الأحداث التي تنشر رسالة وتحديد شكل كل رسالة. احتفظ بكود الموصل، أو ابدأ من الأمثلة.

محرر Transformation code يتضمن Slack handler لأحداث payments

Test and Create

ضمن Test this code، اختر نوع حدث وانقر على Simulate. يعرض Result الرسالة التي سيتلقاها Slack. ثم انقر على Create endpoint.

لوحة Test this code مع اختيار payment.succeeded وزر Simulate وزر Create endpoint

Integration Complete!

يرسل Dodo Payments الآن كل حدث مشترك إلى قناة Slack الخاصة بك. لإرسال رسالة اختبار، افتح علامة التبويب Testing الخاصة بـ endpoint، واختر نوع حدث، ثم انقر على Send example.

أمثلة على رمز التحويل

يستبدل كل معالج webhook.payload برسالة Slack ويحافظ على webhook.url، وهو عنوان URL الخاص بـ incoming webhook. تكون مبالغ Dodo Payments بوحدة العملة الأصغر، لذلك تقسم الأمثلة المبلغ على 100 وتعرض رمز العملة. بالنسبة إلى العملات التي لا تستخدم كسورًا عشرية، مثل JPY وKRW، استخدم المبلغ كما هو.

إشعارات الدفع الأساسية

أرسل رسالة نصية عادية عند نجاح الدفع أو فشله أو أثناء معالجته:

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

معالج شامل لجميع الأحداث

أرسل رسالة بالتنسيق نفسه لكل نوع من الأحداث. تحصل الأحداث التي لا يتوفر لها 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:

استخدم مرفقات الرسائل مع الألوان والحقول، حتى يكون كل حدث واضحًا ويسهل اتخاذ إجراء بشأنه.
أدرج البيانات الأساسية، مثل المبلغ والبريد الإلكتروني للعميل والمعرّفات، حتى يتمكن فريقك من العثور على السجل بسرعة.
طابق اللون مع نوع الحدث: الأخضر (good) للنجاح، والأحمر (danger) للنزاعات أو حالات الفشل، والأصفر (warning) للإلغاءات، والأزرق (#3aa3e3) للأحداث الإعلامية.
أضف طابعًا زمنيًا (ts)، حتى تعرض كل رسالة وقت وقوع الحدث.

التعامل مع البيانات الحساسة: لا تنشر قيمًا حساسة، مثل مفاتيح الترخيص الكاملة أو البيانات الشخصية، في Slack. اقتطعها أو أخفِ أجزاء منها، كما يفعل حقل مفتاح الترخيص في مثال جميع الأحداث.

استكشاف الأخطاء وإصلاحها

Notifications Not Appearing in Slack

تحقق من صحة عنوان URL الخاص بـ Slack webhook ومن أن تطبيق Slack المرتبط به لا يزال مثبتًا.
تحقق من أن رمز التحويل هو JavaScript صالح.
تحقق من وقوع الأحداث التي اشتركت فيها. لإرسال أحدها، استخدم Send example ضمن علامة التبويب Testing الخاصة بنقطة النهاية.
تحقق من تفعيل Incoming Webhooks في تطبيق Slack ومن قدرته على النشر في القناة.

Transformation Errors

افتح علامة التبويب Logs ضمن Developer → Webhooks وتحقق من استجابة عملية التسليم الفاشلة.
تحقق من تطابق حقول الحمولة التي يقرأها رمزك مع حمولة الحدث الخاصة بنوع الحدث ذلك.
اختبر رمزك باستخدام Simulate وحمولة نموذجية.
تحقق من وجود كل حقل يقرأه رمزك. يمكن أن تكون الحقول الاختيارية، مثل error_message، null.

Missing Event Types

تحقق من تحديد الحدث ضمن Subscribed events. لتغيير التحديد، افتح نقطة النهاية وانقر على Edit.
تحقق من أن موصل Slack يدعم الحدث. تعرض Subscribed events الأحداث التي يدعمها الموصل فقط.
تحقق من أن التحويل يحتوي على case للحدث. تترك الأمثلة الأحداث الأخرى دون تغيير، ويرفضها Slack.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

المقدمة

البدء

أمثلة على رمز التحويل

إشعارات الدفع الأساسية

إشعارات الاشتراكات المنسقة

إشعارات إدارة النزاعات

معالج شامل لجميع الأحداث

أفضل الممارسات

استكشاف الأخطاء وإصلاحها

​المقدمة

​البدء

​أمثلة على رمز التحويل

​إشعارات الدفع الأساسية

​إشعارات الاشتراكات المنسقة

​إشعارات إدارة النزاعات

​معالج شامل لجميع الأحداث

​أفضل الممارسات

​استكشاف الأخطاء وإصلاحها

المقدمة

البدء

أمثلة على رمز التحويل

إشعارات الدفع الأساسية

إشعارات الاشتراكات المنسقة

إشعارات إدارة النزاعات

معالج شامل لجميع الأحداث

أفضل الممارسات

استكشاف الأخطاء وإصلاحها