وب‌هوک و اتصال به CRM

ساخت اتصال

POST /v1/webhooks با url، events و enabled یک اتصال HTTPS عمومی می‌سازد. events می‌تواند batch.completed، batch.cancelled، agent.lead، agent.handoff یا budget.threshold باشد. حداکثر ۱۰ اتصال در هر پروژه. کلید secret فقط هنگام ساخت برمی‌گردد؛ آن را در سرور گیرنده ذخیره کن. مدیریت به webhooks:write و خواندن به webhooks:read نیاز دارد.

بررسی امضا

هدر X-Sarovi-Timestamp زمان Unix و X-Sarovi-Signature برابر v1= به‌اضافهٔ HMAC-SHA256 از timestamp + نقطه + بدنهٔ خام، با secret است. امضا را پیش از JSON parsing و با مقایسهٔ زمان ثابت بررسی کن. نمونهٔ webhook.mjs در همهٔ بسته‌های آماده وجود دارد. زمان قدیمی‌تر از ۵ دقیقه را رد کن.

تحویل

هر رویداد id ثابت دارد و ممکن است بیش از یک بار تحویل شود. پیش از ایجاد lead یا booking در CRM، id را در جدول با کلید یکتا ذخیره کن. پاسخ 2xx تحویل را تأیید می‌کند؛ خطاها حداکثر ۶ بار با فاصلهٔ افزایشی تکرار می‌شوند. GET /v1/webhooks/deliveries وضعیت، تعداد تلاش و کد HTTP را می‌دهد. DELETE /v1/webhooks/{id} اتصال را حذف می‌کند. تغییرات تیم را در همین پروژه مدیریت کن.

اتصال ساده

در n8n یا سرور خود یک دریافت‌کنندهٔ HTTPS بساز، امضا و رویداد یکتا را بررسی کن، سپس با توجه به type شاخه‌بندی کن: lead به CRM، handoff به صف پشتیبانی و batch به دریافت فایل خروجی. درخواست نوبت را فقط پس از تأیید سیستم تقویم، قطعی به مشتری اعلام کن.