وب‌هوک‌ها

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

آخرین بازنگری: 2026-08-23

وب‌هوک اینجا یعنی چه

هر تغییر وضعیت در یک فضای کاری یک رویداد می‌نویسد - ساخته‌شدن مخاطب، برنده‌شدن معامله، پرداخت فاکتور. اشتراک وب‌هوک یک دستور دائمی است برای POST کردن این رویدادها - همان لحظه که رخ می‌دهند - به نشانی‌ای که شما کنترل می‌کنید.

به‌جای فراخوانی زمان‌بندی‌شدهٔ GET /events از وب‌هوک استفاده کنید. نظرسنجی دوره‌ای تأخیری به شما تحمیل می‌کند که نمی‌توانید از بینش ببرید و برای فضای کاری هم به‌ازای هر بازه و هر یکپارچه‌سازی یک درخواست هزینه دارد؛ وب‌هوک ظرف چند ثانیه از تغییر می‌رسد و وقتی خبری نیست هیچ هزینه‌ای ندارد.

ساختن اشتراک

در برنامه از مسیر تنظیمات ← وب‌هوک‌ها بسازید، یا از راه API با مجوز webhooks.write.

bash·اشتراک

curl -sS -X POST "$CLIENTO_HOST/api/v1/webhooks" \
  -H "Authorization: Bearer $CLIENTO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse sync",
    "description": "Mirrors contacts and deals into the data warehouse",
    "target_url": "https://hooks.example.com/cliento",
    "event_types": ["ContactCreated", "ContactUpdated", "DealWon"],
    "max_attempts": 5,
    "is_active": true
  }'

json·پاسخ - تنها باری که راز نشان داده می‌شود

{
  "id": 7,
  "name": "Warehouse sync",
  "target_url": "https://hooks.example.com/cliento",
  "event_types": ["ContactCreated", "ContactUpdated", "DealWon"],
  "secret": "whsec_M2Yx…",
  "max_attempts": 5,
  "is_active": true,
  "last_delivery_at": null,
  "created_at": "2026-08-23T10:20:00"
}

فیلد	معنا
`target_url`	مقصد POST. باید HTTPS و از اینترنت در دسترس باشد.
`event_types`	کدام رویدادها فرستاده شوند. `["*"]` یعنی همه.
`extra_headers`	هدرهای ثابتی که به هر تحویل اضافه می‌شوند - مثلاً یک توکن مشترک برای درگاه خودتان.
`masked_fields`	فیلدهایی که این مقصد هرگز نباید دریافت کند. پایین‌تر ببینید.
`max_attempts`	تعداد تلاش‌ها پیش از رهاکردن یک تحویل. پیش‌فرض ۵.
`is_active`	برای توقف بدون حذف، false بگذارید - تحویل‌های در صف آنگاه رها می‌شوند.

نشانی شما باید چه کند

HTTPS باشد و از بیرون در دسترس. نشانی خصوصی هرگز فراخوانده نمی‌شود.
پاسخ 2xx بدهد یعنی «دریافت شد». هر چیز دیگری - از جمله ریدایرکت - شکست به حساب می‌آید و دوباره تلاش می‌شود.
زیر ۱۰ ثانیه پاسخ بدهد. این تایم‌اوت سوکت است؛ پاسخ کندتر یک تلاش ناموفق است، حتی اگر بعداً پردازشش کنید.
کار را بعداً انجام دهید. بررسی کنید، در صف بگذارید، ۲۰۰ برگردانید. پردازش درجا همان چیزی است که یک پایگاه دادهٔ کند را به توفان تلاش دوباره تبدیل می‌کند.
تکراری‌ها را بپذیرد. تحویل «دست‌کم یک‌بار» است - راهنمای تحویل را ببینید.

بار داده

هر تحویل یک POST از نوع JSON با همان پاکت است. ‏payload خودِ رویداد است و سه فیلد پیرامونش فرادادهٔ خود تحویل‌اند.

http·درخواستی که دریافت می‌کنید

POST /cliento HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
X-Cliento-Signature: sha256=6b2f…
X-Cliento-Delivery-Id: 88213
X-Cliento-Event-Type: ContactCreated

json·بدنه

{
  "delivery_id": 88213,
  "event_type": "ContactCreated",
  "timestamp": "2026-08-23T10:21:07Z",
  "payload": {
    "id": 91442,
    "tenant_id": 17,
    "user_id": 5,
    "entity_type": "contact",
    "entity_type_label": { "en": "Contact", "fa": "مخاطب", "ar": "جهة اتصال" },
    "entity_id": 4182,
    "event_type": "ContactCreated",
    "event_type_label": { "en": "Contact created", "fa": "مخاطب ایجاد شد", "ar": "تم إنشاء جهة الاتصال" },
    "source": "api",
    "metadata": { "email": "sara@example.com" },
    "occurred_at": "2026-08-23T10:21:06"
  }
}

فیلد	کاربرد
`delivery_id`	حذف تکراری‌ها. در تلاش دوباره همان عدد است؛ برای تحویل واقعاً تازه، عددی تازه.
`event_type`	مسیریابی. یک کد ماشینی پایدار.
`timestamp`	زمان ساخته‌شدن تحویل (UTC).
`payload.entity_type` / `entity_id`	کدام رکورد تغییر کرده - اگر ردیف کامل را لازم دارید از راه API بخوانید.
`payload.metadata`	افزوده‌های ویژهٔ همان رویداد. با نوع رویداد فرق می‌کند؛ کلیدهای ناشناخته را اختیاری بدانید.

رویدادهای موجود

نوع رویداد نامی PascalCase با ساختار <موجودیت><فعل گذشته> است. به‌جای * دقیقاً همان نام‌هایی را مشترک شوید که برایشان کد دارید، تا نوع رویداد تازه‌ای که به محصول اضافه می‌شود سر و کله‌اش در نشانی‌ای که کدی برایش ندارد پیدا نشود.

http·نمونه‌ای از فهرست

ContactCreated        ContactUpdated        ContactDeleted
LeadCreated           LeadStatusChanged     LeadConverted
DealCreated           DealStageChanged      DealWon            DealLost
TaskCreated           TaskUpdated
PipelineCreated       PipelineStageUpdated
TagCreated            SegmentUpdated        CampaignCreated

فهرست کامل و به‌روز همان چیزی است که در دفتر رویدادهای فضای کاری خودتان می‌بینید: GET /events رویدادهای واقعی را با event_typeشان برمی‌گرداند و صفحهٔ تنظیمات ← وب‌هوک‌ها همان کاتالوگ را به‌صورت انتخابگر ارائه می‌دهد. هر دو از خودِ محصول ساخته می‌شوند، پس هیچ‌کدام آن‌طور که یک فهرست دستیِ اینجا کهنه می‌شود کهنه نمی‌شوند.

بیرون نگه‌داشتن فیلدها از بار داده

‏masked_fields فیلدهایی را نام می‌برد که این مقصد هرگز نباید دریافت کند - مثلاً شماره تلفنی که می‌تواند از CRM شما بیرون برود اما نباید از کشور خارج شود. ‏GET /webhooks/maskable-fields کاتالوگ کلیدها را فهرست می‌کند.

bash·ماسک هنگام خروج

curl -sS -X PATCH "$CLIENTO_HOST/api/v1/webhooks/7" \
  -H "Authorization: Bearer $CLIENTO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "masked_fields": ["contact.phone", "contact.email"] }'

ماسک‌کردن پیش از ذخیرهٔ تحویل انجام می‌شود؛ پس ردیف در صف از همان ابتدا ماسک‌شده است و تلاش دوباره نمی‌تواند نسخهٔ اصلی را بفرستد. همین یعنی GET /webhooks/{subscription_id}/deliveries - دفتر تحویل‌ها - هرگز نسخهٔ ماسک‌نشده نگه نمی‌دارد.