Webhook تلفن ابری همکاران

Webhook چیست؟

Webhook یک روش اطلاع‌رسانی خودکار بین سامانه‌هاست. هر زمان رویدادی در مرکز تماس شما رخ دهد، تلفن ابری همکاران اطلاعات آن رویداد را با یک درخواست POST به آدرس تعیین‌شده ارسال می‌کند.

شروع سریع

1. یک آدرس عمومی و امن HTTPS در نرم‌افزار خود ایجاد کنید.
2. آدرس را در تنظیمات یکپارچه‌سازی پنل تلفن ابری ثبت کنید.
3. درخواست‌های POST با بدنه JSON را دریافت کنید.
4. پس از دریافت، سریعاً یک پاسخ HTTP از خانواده 2xx برگردانید.
5. پردازش اصلی را در صف یا پردازش پس‌زمینه نرم‌افزار خود انجام دهید.

POST https://example.com/integrations/hamkaran/webhook
Content-Type: application/json

تنظیم آدرس مقصد

آدرس مقصد باید از اینترنت قابل دسترس باشد و درخواست‌های POST را بپذیرد.

ساختار درخواست

درخواست‌ها با بدنه JSON ارسال می‌شوند. فیلدهای هر رویداد ممکن است متفاوت باشند؛ اما شناسه تماس برای ارتباط‌دادن رویدادها استفاده می‌شود.

POST /integrations/hamkaran/webhook HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Hamkaran-Cloud-Webhook/1.0

{
  "event_name": "Cdr",
  "unique_id": "1784104200.3765",
  "source": "09121234567",
  "destination": "201",
  "disposition": "ANSWERED"
}

پاسخ مورد انتظار

سرور مقصد باید پس از پذیرش رویداد، یکی از وضعیت‌های موفق HTTP را برگرداند.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}

امنیت و اعتبارسنجی

آدرس وب‌هوک را محرمانه نگه دارید و در سمت سرور کنترل‌های امنیتی متناسب با زیرساخت خود اعمال کنید.

• فقط اتصال HTTPS را قبول کنید.
• Payload دریافتی را پیش از استفاده اعتبارسنجی کنید.
• برای جلوگیری از پردازش تکراری، unique_id و نوع رویداد را ذخیره کنید.
• اطلاعات حساس را در Log عمومی ثبت نکنید.
• محدودیت اندازه درخواست و Rate Limit منطقی تعریف کنید.

تحویل، تلاش مجدد و رویداد تکراری

در شبکه‌های توزیع‌شده ممکن است یک رویداد با تأخیر یا بیش از یک مرتبه دریافت شود. دریافت‌کننده باید Idempotent طراحی شود.

فهرست رویدادها

رویداد Newstate

هنگامی ارسال می‌شود که وضعیت یک کانال تماس تغییر کند؛ برای مثال تماس در حال زنگ‌خوردن یا پاسخ داده شده باشد.

{
  "event_name": "Newstate",
  "unique_id": "1784104200.3765",
  "channel_state": "Ringing",
  "source": "09121234567",
  "destination": "201",
  "timestamp": "2026-07-15T10:30:02+03:30"
}

رویداد Hangup

هنگام قطع‌شدن یک کانال تماس ارسال می‌شود. در تماس‌های دارای صف، انتقال یا چند داخلی ممکن است بیش از یک Hangup برای جریان کلی تماس مشاهده شود.

{
  "event_name": "Hangup",
  "unique_id": "1784104200.3765",
  "source": "09121234567",
  "destination": "201",
  "cause": "Normal Clearing",
  "timestamp": "2026-07-15T10:32:16+03:30"
}

رویداد CDR

CDR گزارش نهایی تماس است و معمولاً بهترین رویداد برای ثبت نتیجه نهایی مکالمه در CRM محسوب می‌شود.

{
  "event_name": "Cdr",
  "unique_id": "1784104200.3765",
  "source": "09121234567",
  "destination": "201",
  "type": "incoming_call",
  "disposition": "ANSWERED",
  "duration": 136,
  "billable_seconds": 124,
  "start_time": "2026-07-15T10:30:00+03:30",
  "answer_time": "2026-07-15T10:30:12+03:30",
  "end_time": "2026-07-15T10:32:16+03:30"
}

رویداد Voicemail

پس از ثبت پیام جدید در صندوق صوتی ارسال می‌شود و می‌تواند برای ایجاد تیکت، اعلان یا ذخیره پیام در CRM استفاده شود.

{
  "event_name": "voiceMail",
  "unique_id": "vm_L3Zhci9zcG9vbC9hc3Rlcmlzay8...",
  "source": "09121234567",
  "mailbox": "201",
  "duration": 34,
  "created_at": "2026-07-15T11:04:10+03:30"
}

ارتباط رویدادهای یک تماس

یک تماس می‌تواند در طول مسیر خود چند رویداد ایجاد کند. برای اتصال اطلاعات، شناسه‌های تماس را در نرم‌افزار خود نگهداری کنید.

نمونه پیاده‌سازی با Node.js

import express from "express";

const app = express();
app.use(express.json({ limit: "1mb" }));

app.post("/integrations/hamkaran/webhook", async (req, res) => {
  const event = req.body;

  if (!event?.event_name || !event?.unique_id) {
    return res.status(400).json({ received: false });
  }

  // پاسخ سریع به سرویس
  res.status(200).json({ received: true });

  // پردازش اصلی در Queue انجام شود
  await webhookQueue.add("hamkaran-event", event, {
    jobId: `${event.event_name}:${event.unique_id}`
  });
});

app.listen(3000);

عیب‌یابی