.svg?fit=max&auto=format&n=5dFUa43uNFVHhpls&q=85&s=0676273c9e1c58f0a7d6694269d14045)
وبهوکهای معامله
وبهوکهای معامله اطلاعات معامله را پس از ایجاد یا ویرایش آن به آدرس مقصد ارسال میکنند. ساختار کلی Payload در هر دو رویداد یکسان است؛ با این تفاوت که در وبهوک ویرایش، آرایهchanges مشخص میکند کدام اطلاعات معامله در همان عملیات تغییر کردهاند.
ساختار داده ارسالی
object
اطلاعات کامل معاملهای است که وبهوک برای آن ارسال شده است. در وبهوک ایجاد، این Object وضعیت معاملهای تازه ایجادشده را نشان میدهد و در وبهوک ویرایش، آخرین وضعیت همان معامله را پس از اعمال تغییرات در اختیار شما قرار میدهد.
Show property
Show property
string
شناسه معاملهای است که این وبهوک برای آن ارسال شده است. در وبهوک ایجاد، این مقدار شناسه معاملهای است که تازه در دیدار ساخته شده و در وبهوک ویرایش، شناسه همان معاملهای است که یکی از اطلاعات آن تغییر کرده است. این مقدار را برای اتصال رویدادهای مختلف به یک معامله و بهروزرسانی رکورد متناظر در سیستم مقصد استفاده کنید.
string
شناسه بیزدامنهای است که معامله داخل آن قرار دارد. این مقدار مشخص میکند رویداد مربوط به کدام حساب یا فضای کاری دیدار است و زمانی اهمیت دارد که یک سرویس، وبهوکهای چند بیزدامنه را در یک آدرس مشترک دریافت میکند.
string
شناسه کاربری است که در زمان ارسال وبهوک مسئول پیگیری و پیشبرد این معامله است. این همان Userی است که معامله در دیدار به او واگذار شده و مسئول ادامه مذاکره، پیگیری مشتری و رساندن معامله به نتیجه محسوب میشود. در وبهوک ویرایش، تغییر این مقدار یعنی مسئول معامله عوض شده است.
string
شناسه شخص اصلی طرف معامله است. این مقدار مشخص میکند فروش یا مذاکره با کدام شخص در جریان است. در وبهوک ایجاد، شناسه شخصی را نشان میدهد که معامله برای او ساخته شده و در وبهوک ویرایش، آخرین شخص متصل به معامله را برمیگرداند.
string
شناسه شرکتی است که معامله به آن مربوط میشود؛ برای مثال شرکتی که شخص اصلی در آن کار میکند یا خرید برای آن انجام میشود. اگر معامله به هیچ شرکتی متصل نباشد، این مقدار ممکن است شناسه صفر ارسال شود. در وبهوک ویرایش، تغییر این مقدار یعنی شرکت مرتبط با معامله عوض شده است.
string
شناسه شیوه آشنایی ثبتشده برای معامله است و نشان میدهد این فرصت فروش از چه کانالی وارد شده؛ برای مثال وبسایت، تبلیغات یا معرفی مشتری. در وبهوک ایجاد، منبع اولیه معامله را نشان میدهد و در وبهوک ویرایش، آخرین منبع انتخابشده برای معامله را برمیگرداند.
string
شناسه مرحلهای از کاریز معامله است که معامله در زمان ارسال وبهوک داخل آن قرار دارد. این مقدار جای فعلی معامله را در فرایند فروش مشخص میکند؛ برای مثال «بررسی نیاز»، «ارسال پیشنهاد» یا «مذاکره». در وبهوک ویرایش، تغییر این مقدار یعنی معامله به مرحله دیگری از کاریز جابهجا شده است.
string
شناسه کاریزی است که معامله داخل آن مدیریت میشود؛ برای مثال کاریز فروش سازمانی یا فروش آنلاین. این مقدار مشخص میکند معامله متعلق به کدام فرایند فروش است. در وبهوک ویرایش، تغییر این مقدار یعنی معامله به کاریز دیگری منتقل شده است.
string
شناسه دلیل شکستی است که برای معامله ناموفق انتخاب شده است. این مقدار زمانی معنا دارد که وضعیت معامله شکستخورده باشد و مشخص میکند معامله به کدام دلیل تعریفشده در دیدار از دست رفته است. اگر دلیل شکست از فهرست آماده انتخاب نشده باشد، ممکن است این مقدار شناسه صفر باشد و متن دلیل در
data.LostReasonOther قرار بگیرد.string
شناسه کاربری است که معامله را برای اولین بار در دیدار ایجاد کرده است. این کاربر ایجادکننده رکورد است و لزوماً با مسئول فعلی معامله یا کاربری که آخرین ویرایش را انجام داده یکسان نیست. این مقدار در ویرایشهای بعدی همچنان ایجادکننده اولیه معامله را نشان میدهد.
array
فهرست شناسه برچسبهایی است که در زمان ارسال وبهوک به معامله متصل هستند؛ برای مثال برچسبهایی مانند «مهم» یا «نیاز به پیگیری مدیر». هر عضو Array شناسه یک برچسب معامله است. در وبهوک ویرایش، این Array وضعیت نهایی برچسبهای معامله پس از اضافه یا حذفشدن برچسبها را نشان میدهد.
string
تاریخ و زمانی است که معامله به وضعیت موفق منتقل شده است. این مقدار زمان واقعی موفقشدن معامله را نشان میدهد و با زمان ایجاد معامله یا تاریخ احتمالی بستهشدن آن متفاوت است. برای معاملهای که هنوز موفق نشده، مقدار موجود باید با رفتار Payload همان رکورد تفسیر شود.
string
تاریخ و زمانی است که معامله به وضعیت ناموفق منتقل شده است. این مقدار مشخص میکند معامله چه زمانی بهعنوان شکستخورده ثبت شده و با زمان ایجاد یا آخرین ویرایش معامله متفاوت است. برای معاملهای که هنوز شکست نخورده، مقدار موجود باید با رفتار Payload همان رکورد تفسیر شود.
string
تاریخ و زمانی است که معامله برای اولین بار در دیدار ایجاد شده است. در وبهوک ایجاد، زمان ثبت معامله تازه را نشان میدهد و در وبهوک ویرایش نیز همان زمان ایجاد اولیه باقی میماند؛ بنابراین این فیلد زمان آخرین ویرایش معامله نیست.
string
تاریخ مورد انتظار برای نهاییشدن معامله است؛ یعنی زمانی که تیم فروش پیشبینی کرده معامله تا آن تاریخ موفق یا ناموفق شود. این تاریخ برای برنامهریزی و پیشبینی فروش استفاده میشود و الزاماً با زمان واقعی موفقشدن یا شکستخوردن معامله یکسان نیست. اگر تاریخی ثبت نشده باشد، مقدار
null ارسال میشود.string
عنوان معاملهای است که این وبهوک برای آن ارسال شده است. کاربران دیدار معامله را در کارت معامله، کاریز و فهرست معاملات با همین عنوان میبینند. در وبهوک ایجاد، عنوان معامله تازه ثبتشده و در وبهوک ویرایش، آخرین عنوان ذخیرهشده پس از تغییر را دریافت میکنید.
string
توضیحات تکمیلی ثبتشده برای معامله است و میتواند شامل زمینه فروش، نیاز مشتری، شرایط مذاکره یا نکات لازم برای پیگیری باشد. در وبهوک ویرایش، این مقدار متن نهایی توضیحات پس از اعمال تغییرات را نشان میدهد. اگر توضیحی ثبت نشده باشد، مقدار
null ارسال میشود.string
شناسه سایر اشخاص یا شرکتهای مرتبط با معامله است؛ یعنی مخاطبانی غیر از شخص اصلی
data.PersonId و شرکت اصلی data.CompanyId که در این معامله نقش دارند. این مقدار کمک میکند همه افراد و سازمانهای درگیر در تصمیمگیری یا پیگیری معامله را به رکورد متناظر در سیستم مقصد متصل کنید.string
عنوان شیوه آشنایی دیگری است که برای معامله ثبت شده؛ زمانی که منبع واقعی معامله در فهرست منابع تعریفشده دیدار وجود نداشته باشد. اگر معامله از یکی از منابع آماده استفاده کند، این مقدار معمولاً خالی یا
null است و منبع از طریق data.SourceId مشخص میشود.string
متن دلیل شکست دیگری است که برای معامله ثبت شده؛ زمانی که دلیل واقعی شکست در فهرست دلایل تعریفشده دیدار وجود نداشته باشد. این فیلد برای معاملههای شکستخورده معنا دارد و در کنار
data.LostReasonId مشخص میکند علت ازدسترفتن فرصت فروش چه بوده است.string
توضیح تکمیلی درباره دلیل شکست معامله است. این متن جزئیاتی را نگهداری میکند که فقط با انتخاب یک دلیل شکست مشخص نمیشوند؛ برای مثال اینکه مشتری چرا پیشنهاد رقیب را انتخاب کرده یا کدام شرط قرارداد پذیرفته نشده است. در وبهوک ویرایش، آخرین توضیح ذخیرهشده برای شکست معامله ارسال میشود.
number
مبلغ فعلی معامله است و ارزش مالی ثبتشده برای این فرصت فروش را نشان میدهد. این مبلغ برای گزارشها و پیشبینی فروش استفاده میشود و باید همراه با
data.CurrencyId تفسیر شود. در وبهوک ویرایش، این مقدار مبلغ نهایی معامله پس از تغییر را نشان میدهد.number
مبلغ تقریبی یا برآوردشده معامله است. این مقدار زمانی کاربرد دارد که ارزش نهایی معامله هنوز قطعی نیست و تیم فروش یک برآورد اولیه از مبلغ فرصت فروش ثبت کرده است. در وبهوک ویرایش، آخرین مبلغ برآوردشده پس از تغییر ارسال میشود.
number
شناسه ارزی است که مبلغهای معامله براساس آن ثبت شدهاند. برای نمایش یا محاسبه صحیح
data.Price و data.EstimatedPrice باید این مقدار را در کنار مبلغها نگهداری کنید؛ زیرا عدد مبلغ بدون مشخصبودن ارز معنای کامل ندارد.number
کد عددی معامله در دیدار است که برای شناسایی و جستوجوی سادهتر معامله در رابط کاربری یا گزارشها استفاده میشود. این مقدار با
data.Id فرق دارد: Id شناسه فنی و یکتای رکورد است، اما Code کدی است که معمولاً برای ارجاع انسانی به معامله استفاده میشود.number
درصد احتمال موفقشدن معامله است. این مقدار نشان میدهد تیم فروش یا تنظیمات مرحله فعلی، شانس تبدیلشدن این فرصت به فروش موفق را چقدر در نظر گرفتهاند و میتواند برای محاسبه فروش وزنی و پیشبینی درآمد استفاده شود.
boolean
مشخص میکند مبلغ معامله بهعنوان پرداختشده ثبت شده است یا خیر. مقدار
true یعنی معامله در دیدار پرداختشده علامت خورده و مقدار false یعنی هنوز پرداختشده محسوب نمیشود. در وبهوک ویرایش، تغییر این مقدار میتواند ثبت یا برداشتهشدن وضعیت پرداخت را نشان دهد.boolean
مشخص میکند معامله حذف شده است یا خیر. مقدار
true یعنی معامله حذف شده و مقدار false یعنی رکورد همچنان حذفنشده است. این فیلد به سیستم مقصد کمک میکند وضعیت حذف معامله را بدون حذف فیزیکی فوری دادههای مرتبط مدیریت کند.number
سطح مشاهده فعلی معامله را مشخص میکند؛ یعنی این معامله براساس تنظیمات دسترسی دیدار برای چه کاربران یا گروههایی قابل مشاهده است. در وبهوک ایجاد، سطح مشاهده اولیه معامله و در وبهوک ویرایش، آخرین سطح مشاهده ذخیرهشده پس از تغییر ارسال میشود.
number
وضعیت فعلی معامله در چرخه فروش را مشخص میکند؛ یعنی نشان میدهد معامله هنوز باز و در حال پیگیری است، با موفقیت بسته شده یا شکست خورده است. در وبهوک ایجاد، وضعیت اولیه معامله و در وبهوک ویرایش، وضعیت نهایی پس از تغییر ارسال میشود. زمان موفق یا شکستشدن معامله در
data.ChangeToWonTime و data.ChangeToLossTime قرار میگیرد.object
مقادیر فیلدهای اضافهای است که برای معامله در این بیزدامنه تعریف شدهاند. نام هر property کلید فنی یک Custom Field معامله و مقدار آن، دادهای است که برای همین معامله در آن فیلد ثبت شده است. در وبهوک ویرایش، این Object آخرین مقادیر فیلدهای اضافه را پس از اعمال تغییرات نشان میدهد.
array
فهرست محصولات یا خدماتی است که در زمان ارسال وبهوک داخل معامله قرار دارند. هر عضو Array یک ردیف مستقل از اقلام معامله را نشان میدهد و میتواند اطلاعاتی مانند محصول، زیرمحصول، تعداد، قیمت واحد، مبلغ، تخفیف، مالیات و توضیحات همان ردیف را داشته باشد. در وبهوک ویرایش، این Array وضعیت نهایی اقلام معامله پس از اضافه، حذف یا ویرایش محصولات را برمیگرداند.
array
تغییراتی که باعث ارسال وبهوک ویرایش معامله شدهاند در این Array قرار میگیرند. در وبهوک ایجاد،
changes خالی است؛ چون معامله تازه ساخته شده و نسخه قبلیای برای مقایسه وجود ندارد. در وبهوک ویرایش، هر عضو مشخص میکند کدام فیلد تغییر کرده، مقدار آن پیش از ویرایش چه بوده و پس از ویرایش به چه مقداری تبدیل شده است. Object data وضعیت نهایی معامله را نشان میدهد و changes فقط تغییرات همان عملیات را گزارش میکند.Show property
Show property
string
نام فیلدی از معامله است که در این عملیات ویرایش تغییر کرده است. این مقدار مشخص میکند
before و after مربوط به کدام بخش از اطلاعات معامله هستند.string
مقدار فیلد پیش از انجام این ویرایش است. با مقایسه آن با
changes[].after میتوانید دقیقاً تشخیص دهید اطلاعات معامله از چه مقداری تغییر کرده است. نوع مقدار به فیلد نوشتهشده در propertyName بستگی دارد و میتواند رشته، عدد، Boolean، Object، Array یا null باشد.string
مقدار فیلد پس از انجام و ذخیره ویرایش است. این مقدار نتیجه نهایی همان تغییر را نشان میدهد و باید با مقدار متناظر آن در Object
data همخوان باشد.object
اطلاعات فنی مربوط به خود رویداد وبهوک است، نه اطلاعات معامله. این Object مشخص میکند چه عملیاتی انجام شده، رویداد متعلق به کدام بیزدامنه و معامله است، چه کاربری آن را ایجاد کرده، تغییر از چه منبعی آمده و Payload توسط کدام تنظیم وبهوک و در چندمین تلاش ارسال شده است.
Show property
Show property
number
کد عددی نوع عملیاتی است که باعث ارسال این وبهوک شده است. براساس نمونهها، مقدار
1 یعنی معامله ایجاد شده و مقدار 2 یعنی معامله ویرایش شده است.string
عنوان متنی همان عملیاتی است که در
meta.actionType بهصورت عددی مشخص شده است. در نمونه ایجاد مقدار Add و در نمونه ویرایش مقدار Change ارسال میشود.string
شناسه بیزدامنهای است که معامله در آن ایجاد یا ویرایش شده است. این مقدار مشخص میکند رویداد وبهوک متعلق به کدام حساب یا فضای کاری دیدار است.
string
شناسه معاملهای است که رویداد وبهوک برای آن ثبت شده است. این مقدار باید به همان رکوردی اشاره کند که اطلاعات کامل آن داخل
data قرار گرفته و معمولاً با data.Id یکسان است.number
کد عددی داخلی نوع موجودیتی است که رویداد برای آن ثبت شده است. در Payload این صفحه، این کد به موجودیت معامله اشاره میکند.
string
عنوان فنی موجودیتی است که این وبهوک به آن مربوط میشود و نشان میدهد رکورد داخل
data از نوع معامله است.number
شناسه رویدادی است که پس از ایجاد یا ویرایش معامله در سیستم ثبت شده و این Payload براساس آن ساخته شده است. این شناسه مربوط به خود رویداد است، نه شناسه معامله.
boolean
مشخص میکند تغییر معامله در قالب یک عملیات گروهی انجام شده است یا خیر. مقدار
true یعنی این رویداد نتیجه ویرایش گروهی بوده و مقدار false یعنی معامله بهصورت تکی ایجاد یا ویرایش شده است.string
زمانی است که رویداد ایجاد یا ویرایش معامله در دیدار ثبت شده و Payload وبهوک براساس آن تولید شده است. این زمان لزوماً با تاریخهای داخل خود معامله یکسان نیست.
string
شناسه کاربری است که عملیات منجر به ارسال این وبهوک را انجام داده است. در رویداد ایجاد، کاربری را نشان میدهد که معامله را ساخته و در رویداد ویرایش، کاربری را مشخص میکند که تغییر را انجام داده است.
number
شناسه تنظیم وبهوکی است که این Payload را به آدرس مقصد ارسال کرده است. این مقدار برای تشخیص وبهوک تعریفشدهای که رویداد از طریق آن ارسال شده کاربرد دارد.
number
کد عددی منبعی است که عملیات ایجاد یا ویرایش از طریق آن انجام شده است. عنوان قابلخواندن همین منبع در
meta.changeSourceTitle قرار میگیرد.string
عنوان متنی منبعی است که معامله از طریق آن ایجاد یا ویرایش شده است. برای مثال مقدار
Api یعنی عملیات از طریق API انجام شده است.number
شماره تلاش برای ارسال همین رویداد وبهوک به آدرس مقصد است. مقدار
1 یعنی Payload در اولین تلاش ارسال شده است.وبهوک ایجاد معامله چه زمانی ارسال میشود؟
وبهوک ایجاد معامله زمانی ارسال میشود که یک معامله جدید با موفقیت در دیدار ثبت شود. آبجکتdata شامل اطلاعات معامله تازه ایجادشده است و آرایه changes خالی ارسال میشود، چون پیش از این عملیات رکوردی وجود نداشته که فیلدی از آن تغییر کرده باشد.
وبهوک ویرایش معامله چه زمانی ارسال میشود؟
وبهوک ویرایش معامله زمانی ارسال میشود که حداقل یکی از اطلاعات موجود درdata تغییر کند. فیلدهایی که تغییر آنها میتواند باعث ارسال این وبهوک شود عبارتاند از:
data.Iddata.BizDomainIddata.OwnerIddata.PersonIddata.CompanyIddata.SourceIddata.PipelineStageIddata.PipelineIddata.LostReasonIddata.CreatorIddata.LabelIdsdata.ChangeToWonTimedata.ChangeToLossTimedata.RegisterTimedata.ExpectedCloseDatedata.Titledata.Descriptiondata.OtherContactIdsdata.SourceOtherdata.LostReasonOtherdata.LostReasonNotedata.Pricedata.EstimatedPricedata.CurrencyIddata.Codedata.Probabilitydata.IsPaiddata.IsDeleteddata.VisibilityTypedata.Statusdata.Items
data تغییر نکنند، وبهوک ویرایش معامله ارسال نمیشود. آرایه changes عامل Trigger نیست؛ این آرایه نتیجه تغییرات انجامشده را گزارش میکند و data آخرین وضعیت معامله را پس از ویرایش نشان میدهد.
نمونه داده ارسالی
{
"data": {
"Id": "fb2fb2ad-34b1-458d-86a5-ddb68ec3176f",
"BizDomainId": "b8233b92-7a57-42a3-8f3e-59fdbbb6c833",
"OwnerId": "58f610e7-061a-4efc-9a87-af7b31bde808",
"PersonId": "a88c049a-159a-4ce3-8a24-a28f6bc8dacf",
"CompanyId": "00000000-0000-0000-0000-000000000000",
"SourceId": "a618fdba-dced-40c0-aae0-93a364135316",
"PipelineStageId": "1f98965b-d5fa-40e1-be80-b7fcba79e0cf",
"PipelineId": "82063d6f-07b8-4e5b-82ac-b8bea5ed9a38",
"LostReasonId": "00000000-0000-0000-0000-000000000000",
"CreatorId": "58f610e7-061a-4efc-9a87-af7b31bde808",
"LabelIds": [],
"ChangeToWonTime": "2026-08-02T15:25:43.6640351+00:00",
"ChangeToLossTime": "2026-08-02T15:25:43.6640351+00:00",
"RegisterTime": "2026-08-02T15:25:43.6640351+00:00",
"ExpectedCloseDate": null,
"Title": "معامله test",
"Description": null,
"OtherContactIds": null,
"SourceOther": null,
"LostReasonOther": null,
"LostReasonNote": null,
"Price": 50000000,
"EstimatedPrice": 50000000,
"CurrencyId": 258325,
"Code": 0,
"Probability": 100,
"IsPaid": false,
"IsDeleted": false,
"VisibilityType": 1,
"Status": 0,
"Fields": {},
"Items": []
},
"changes": [],
"meta": {
"actionType": 1,
"actionTypeTitle": "Add",
"bizDomainId": "b8233b92-7a57-42a3-8f3e-59fdbbb6c833",
"entityId": "fb2fb2ad-34b1-458d-86a5-ddb68ec3176f",
"entity": 8783,
"entityTitle": "Deal",
"id": 639212811443008227,
"isBulkEdit": false,
"timeStamp": "2026-08-02T15:25:44.3008227Z",
"userId": "58f610e7-061a-4efc-9a87-af7b31bde808",
"webhookId": 32488,
"changeSource": 1,
"changeSourceTitle": "Api",
"attempt": 1
}
}
{
"data": {
"Id": "fb2fb2ad-34b1-458d-86a5-ddb68ec3176f",
"BizDomainId": "b8233b92-7a57-42a3-8f3e-59fdbbb6c833",
"OwnerId": "58f610e7-061a-4efc-9a87-af7b31bde808",
"PersonId": "a88c049a-159a-4ce3-8a24-a28f6bc8dacf",
"CompanyId": "00000000-0000-0000-0000-000000000000",
"SourceId": "a618fdba-dced-40c0-aae0-93a364135316",
"PipelineStageId": "1f98965b-d5fa-40e1-be80-b7fcba79e0cf",
"PipelineId": "82063d6f-07b8-4e5b-82ac-b8bea5ed9a38",
"LostReasonId": "00000000-0000-0000-0000-000000000000",
"CreatorId": "58f610e7-061a-4efc-9a87-af7b31bde808",
"LabelIds": [],
"ChangeToWonTime": "2026-08-02T15:25:43",
"ChangeToLossTime": "2026-08-02T15:25:43",
"RegisterTime": "2026-08-02T15:25:43",
"ExpectedCloseDate": null,
"Title": "معامله test",
"Description": "",
"OtherContactIds": "",
"SourceOther": "",
"LostReasonOther": "",
"LostReasonNote": "",
"Price": 50000000,
"EstimatedPrice": 50000000,
"CurrencyId": 258325,
"Code": 10,
"Probability": 100,
"IsPaid": false,
"IsDeleted": false,
"VisibilityType": 1,
"Status": 0,
"Fields": {},
"Items": []
},
"changes": [
{
"propertyName": "PipelineStageId",
"before": "a5b02fa5-9cb6-49ca-96c9-15a3f0b8bfa0",
"after": "1f98965b-d5fa-40e1-be80-b7fcba79e0cf"
}
],
"meta": {
"actionType": 2,
"actionTypeTitle": "Change",
"bizDomainId": "b8233b92-7a57-42a3-8f3e-59fdbbb6c833",
"entityId": "fb2fb2ad-34b1-458d-86a5-ddb68ec3176f",
"entity": 8783,
"entityTitle": "Deal",
"id": 639212813091378323,
"isBulkEdit": false,
"timeStamp": "2026-08-02T15:28:29.1378323Z",
"userId": "58f610e7-061a-4efc-9a87-af7b31bde808",
"webhookId": 32489,
"changeSource": 1,
"changeSourceTitle": "Api",
"attempt": 1
}
}