Webhooks
احصل على استدعاء موقّع إلى خادمك عندما يصل رد، أو يبدي شخص اهتمامه، أو يرتد بريد إلكتروني، أو تجهز قائمة أو عملية تصدير. متوفرة ابتداءً من خطة Pro.
الأحداث
| الحدث | متى يُطلق | ما يحتويه data |
|---|---|---|
reply.received | ردّ شخص على إحدى حملاتك. تُستبعد إشعارات الغياب التلقائية، إلا إذا أخفت مساحة العمل لديك تصنيف خارج المكتب. ويُطلق أيضًا عندما تنقل ردًا من تصنيف خارج المكتب إلى تصنيف آخر | classification، lead_email، campaign_id، subject، snippet، reply_id، lead_id، received_at |
reply.positive | أعطيت ردًا تصنيف مهتم أو طلب اجتماع، في التطبيق أو باستخدام POST /api/v1/inbox/{id}/classify. لا يُطلق إلا عند تغيّر التصنيف، لذا يرسل الرد الواحد reply.received عند وصوله وreply.positive عندما تصنّفه | classification، lead_email، campaign_id، subject، snippet، reply_id، lead_id، received_at |
email.bounced | ارتدّ بريد إلكتروني من إحدى الحملات. لا يُرسل إذا كان ذلك الشخص قد ردّ من قبل | lead_email، campaign_id، subject |
email.unsubscribed | استخدم شخص رابط إلغاء الاشتراك، أو أعطيت ردّه تصنيف إلغاء الاشتراك | classification، lead_email، campaign_id، subject، snippet، وsource عند استخدام رابط إلغاء الاشتراك، أو reply_id وlead_id وreceived_at عندما يأتي من تصنيف |
campaign.paused | أوقف Argorant حملة قيد التشغيل مؤقتًا: استُنفدت رسائل الحملات في خطتك (أو انتهت الفترة التجريبية أو الخطة)، أو أوقفت الحملة نفسها مؤقتًا بسبب حالات الارتداد أو صناديق بريد غير متصلة. الإيقاف المؤقت الذي تقوم به بنفسك لا يرسل شيئًا | campaign_id، campaign_name، reason، message، وcampaign_emails (الخطة) أو metrics وurl (أوقفت نفسها) |
campaign.resumed | عادت رسائل الحملات متاحة (شهر جديد أو خطة أكبر)، فتعود الحملة التي أوقفتها الخطة إلى الإرسال. الإطلاق الذي تقوم به بنفسك لا يرسل شيئًا | campaign_id، campaign_name، reason، message، campaign_emails |
export.ready | اكتملت عملية تصدير. لا يُرسل عند فشلها | job_id، status، total_rows، verified_rows، status_url، download_url، status_api_path، download_api_path |
list.ready | اكتمل ملء قائمة، وكذلك بعد أن تضيف إليها أشخاصًا آخرين. لا يُرسل عند فشل الملء | list_id، list_name، job_id، status، total_items، note، status_url، status_api_path |
verification.completed | اكتمل فحص بريد إلكتروني واحد باستخدام مفتاح API | email، status، deliverable، is_role_based، is_free، is_disposable |
segment.new_matches | أصبح في قائمة بحث محفوظة أشخاص مطابقون أكثر مما كان عند آخر عدّ. تُراجَع القوائم كل 30 دقيقة تقريبًا | list_id، list_name، previous_total، current_total، new_matches |
lead.created | أُضيف أشخاص إلى حملة، في التطبيق أو عبر API أو من ملف أو من قائمة أو بالنقل. تسليم واحد لكل دفعة استقبلتها الحملة، لذا يصل الاستيراد الكبير في عدة عمليات تسليم. يُستبعد الأشخاص الذين أُزيلوا مرة أخرى قبل خروج التسليم | campaign_id، campaign_name، count، leads، ولكل منهم lead_id، email، first_name، last_name، company، title، status، custom_fields، added_at |
campaign.status_changed | تغيّرت حالة حملة، بواسطتك أو بواسطة Argorant: إطلاق أو إيقاف مؤقت أو إيقاف أو أرشفة، أو إيقاف مؤقت بسبب رسائل الحملات أو حالات الارتداد أو صناديق البريد غير المتصلة. ويُطلق أيضًا إلى جانب campaign.paused وcampaign.resumed | campaign_id، campaign_name، from، to، changed_at |
email.sent | خرجت رسائل حملة. يصل خلال دقيقة تقريبًا من الإرسال، بتسليم واحد لكل حملة يضم حتى 100 رسالة | campaign_id، campaign_name، count، emails، ولكل منها email_id، lead_id، lead_email، subject، step، mailbox، sent_at |
reply.label_changed | عيّن شخص تصنيف رد أو غيّره، في صندوق الوارد في التطبيق أو باستخدام POST /api/v1/inbox/{id}/classify. تعيين التصنيف نفسه مرة أخرى لا يرسل شيئًا | reply_id، lead_id، lead_email، campaign_id، subject، from، to، changed_at |
تذهب أحداث الحملات إلى Webhooks مالك مساحة العمل وكل عضو نشط في الفريق، حتى يوجّهها كل شخص إلى أدواته الخاصة. وتذهب عمليات التصدير والقوائم والفحوصات إلى Webhooks الشخص الذي بدأها. وتذهب المطابقات الجديدة إلى Webhooks مالك القائمة.
في أحداث الردود تكون قيمة classification هي null للرد الذي وصل للتو، وتكون قيمتها مفتاح التصنيف بعد أن يعيّن أحدٌ تصنيفًا، مثل positive أو meeting_request. يحمل subject حتى 300 حرف ويحمل snippet حتى 500 حرف من النص العادي. يمثّل reply_id الرد، وlead_id الشخص في الحملة، وreceived_at وقت وصول الرد. قيمة reason في campaign.paused هي campaign_email_allowance عندما توقف الخطة الحملة، وauto_pause_bounce_rate أو auto_pause_inboxes_offline أو auto_pause عندما توقف الحملة نفسها. يوضح campaign_emails.reason سبب نفاد الرسائل (allowance_used أو trial_ended أو plan_ended أو confirm_email) ويكون فارغًا في campaign.resumed.
قيم from وto في campaign.status_changed هي draft أو active أو paused أو completed أو archived. وفي reply.label_changed هي مفاتيح تصنيفات، وتكون from هي null عندما لم يكن للرد تصنيف. تبدأ lead.created وcampaign.status_changed وemail.sent بعد نحو دقيقة من إنشاء أول Webhook يطلبها، ولا يُرسل شيء مما حدث قبل ذلك. عندما يتأخر خادمك كثيرًا، تنتظر استدعاءات email.sent الجديدة حتى يلحق بالركب، ولا يُسقط أي منها.
إذا كنت تقرأ API وفق جدول زمني بدلًا من ذلك، فابدأ كل قراءة قبل نهاية القراءة السابقة ببضع دقائق وتجاوز المعرّفات التي لديك بالفعل. قد يُحفظ صف بعد لحظة من الوقت الذي يحمله، لذا قد تفوته نافذة تبدأ تمامًا حيث انتهت السابقة. لا تحتاج Webhooks إلى أي من ذلك.
إنشاء Webhook
curl -X POST "https://app.argorant.com/api/v1/webhooks" \
-H "Authorization: Bearer $ARGORANT_API_KEY" -H "Idempotency-Key: hook-crm-1" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.yourcompany.example/argorant","events":["reply.positive","email.bounced","export.ready"]}'يجب أن يكون العنوان عنوان https:// عامًا. تحتوي الإجابة على secret التوقيع. يُعرض مرة واحدة فقط، لذا احفظه الآن. يمكن أن يكون لكل حساب حتى 10 Webhooks مفعّلة و50 إجمالًا. إضافة عنوان لديك بالفعل تغيّر ذلك الـ Webhook (الأحداث الجديدة، مع تفعيله) وتجيب بـ 200 مع existing: true ودون سر جديد.
يتطلب إنشاء Webhook خطة Pro أو أعلى، خطتك أنت أو خطة مساحة عمل أنت عضو في فريقها، وإلا تحصل على 402 plan_required. لكل شخص حده الخاص. يجيب الحدث غير المعروف بـ 400 invalid_webhook_events، ويجيب الـ Webhook الحادي عشر المفعّل أو الحادي والخمسون إجمالًا بـ 400 webhook_limit_reached.
| الاستدعاء | ما يفعله |
|---|---|
GET /api/v1/webhooks | الـ Webhooks الخاصة بك وكل حدث يمكنك اختياره |
PATCH /api/v1/webhooks/{id} | يغيّر URL أو الأحداث، أو يوقف التفعيل بـ "active": false |
DELETE /api/v1/webhooks/{id} | يحذفه |
POST /api/v1/webhooks/{id}/test | يرسل استدعاء اختبار واحدًا موقّعًا يحمل data المثال لحدث ما و"test": true |
GET /api/v1/webhooks/{id}/deliveries | الاستدعاءات الأخيرة مع نتيجتها والمحاولة التالية |
ما يستلمه خادمك
POST /hooks/argorant
Content-Type: application/json
User-Agent: Argorant-Webhooks/1.0
X-Argorant-Event: reply.positive
X-Argorant-Delivery: 8842
X-Argorant-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
{"event": "reply.positive", "delivery_id": "8842", "created_at": "2026-11-07T09:15:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}لكل استدعاء المفاتيح الأربعة نفسها: event، وdelivery_id (رقم يُرسل كنص، وهو نفسه X-Argorant-Delivery)، وcreated_at، وdata. أجب بأي حالة 2xx خلال بضع ثوانٍ. نفّذ العمل البطيء بعد أن تجيب. لا تُتّبع عمليات إعادة التوجيه، لذا استخدم العنوان النهائي.
أمثلة على البيانات المرسلة
جسم كامل لكل حدث، كما يستلمه خادمك. يحمل export.ready وlist.ready أيضًا status_api_path (وdownload_api_path لعمليات التصدير)، وهي مسارات أقدم أُبقيت من أجل التكاملات الحالية، وقد حُذفت من الأمثلة أدناه. استخدم status_url وdownload_url.
reply.received
{"event": "reply.received", "delivery_id": "8841", "created_at": "2026-11-07T09:14:03+00:00",
"data": {"classification": null, "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}reply.positive
{"event": "reply.positive", "delivery_id": "8842", "created_at": "2026-11-07T09:15:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}email.bounced
{"event": "email.bounced", "delivery_id": "8843", "created_at": "2026-11-07T09:16:03+00:00",
"data": {"lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Quick question, Maya"}}email.unsubscribed
{"event": "email.unsubscribed", "delivery_id": "8844", "created_at": "2026-11-07T09:17:03+00:00",
"data": {"classification": "unsubscribe", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "", "snippet": "", "source": "unsubscribe_link"}}campaign.paused
{"event": "campaign.paused", "delivery_id": "8845", "created_at": "2026-11-07T09:18:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "reason": "campaign_email_allowance", "message": "Monthly email limit reached. All 300,000 campaign emails for this month are used. Sending resumes on December 1, 2026, or right after an upgrade.", "campaign_emails": {"tier": "pro", "allowance": 300000, "used": 300000, "remaining": 0, "period": "month", "resets_on": "2026-12-01", "reason": "allowance_used", "trial_ends_at": null, "trial_days_left": null}}}campaign.resumed
{"event": "campaign.resumed", "delivery_id": "8846", "created_at": "2026-11-07T09:19:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "reason": "campaign_email_allowance", "message": "Sending resumed.", "campaign_emails": {"tier": "pro", "allowance": 300000, "used": 0, "remaining": 300000, "period": "month", "resets_on": "2027-01-01", "reason": "", "trial_ends_at": null, "trial_days_left": null}}}export.ready
{"event": "export.ready", "delivery_id": "8847", "created_at": "2026-11-07T09:20:03+00:00",
"data": {"job_id": 84213, "status": "done", "total_rows": 500, "verified_rows": 463, "status_url": "/api/v1/exports/84213", "download_url": "/api/v1/exports/84213/download"}}list.ready
{"event": "list.ready", "delivery_id": "8848", "created_at": "2026-11-07T09:21:03+00:00",
"data": {"list_id": "312", "list_name": "DACH CFOs", "job_id": 5120, "status": "done", "total_items": 1188, "note": "1,240 matched: 1,188 added, 52 already in the list.", "status_url": "/api/v1/lists/312"}}verification.completed
{"event": "verification.completed", "delivery_id": "8849", "created_at": "2026-11-07T09:22:03+00:00",
"data": {"email": "maya.chen@linfieldsystems.example", "status": "valid", "deliverable": true, "is_role_based": false, "is_free": false, "is_disposable": false}}segment.new_matches
{"event": "segment.new_matches", "delivery_id": "8850", "created_at": "2026-11-07T09:23:03+00:00",
"data": {"list_id": "312", "list_name": "DACH CFOs", "previous_total": 1188, "current_total": 1214, "new_matches": 26}}lead.created
{"event": "lead.created", "delivery_id": "8851", "created_at": "2026-11-07T09:24:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "count": 2, "leads": [{"lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "email": "maya.chen@linfieldsystems.example", "first_name": "Maya", "last_name": "Chen", "company": "Linfield Systems", "title": "CFO", "status": "pending", "custom_fields": {"tags": ["q4"]}, "added_at": "2026-11-07T08:02:11.204519+00:00"}, {"lead_id": "5e2a7c91-3b4d-4f6e-8a1c-9d0b2e4f6a83", "email": "alex.rivera@linfieldsystems.example", "first_name": "Alex", "last_name": "Rivera", "company": "Linfield Systems", "title": "Head of Finance", "status": "pending", "custom_fields": {"tags": ["q4"]}, "added_at": "2026-11-07T08:02:11.204519+00:00"}]}}campaign.status_changed
{"event": "campaign.status_changed", "delivery_id": "8852", "created_at": "2026-11-07T09:25:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "from": "draft", "to": "active", "changed_at": "2026-11-07T08:05:37.918204+00:00"}}email.sent
{"event": "email.sent", "delivery_id": "8853", "created_at": "2026-11-07T09:26:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "count": 1, "emails": [{"email_id": "9a7b5c3d-1e2f-4a6b-8c0d-2e4f6a8b0c1d", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "lead_email": "maya.chen@linfieldsystems.example", "subject": "Quick question, Maya", "step": 1, "mailbox": "outreach@yourcompany-mail.example", "sent_at": "2026-11-07T08:31:12.550731+00:00"}]}}reply.label_changed
{"event": "reply.label_changed", "delivery_id": "8854", "created_at": "2026-11-07T09:27:03+00:00",
"data": {"reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "from": null, "to": "meeting_request", "changed_at": "2026-11-07T09:20:41Z"}}استدعاءات الاختبار
يرسل POST /api/v1/webhooks/{id}/test استدعاءً واحدًا موقّعًا يحمل data المثال لأحد أحداث الـ Webhook، مثل ما ورد أعلاه، مع "test": true، حتى يميّز كودك الاختبار من الحدث الحقيقي. أرسل {"event": "lead.created"} لاختيار الحدث، وبدونه يُستخدم أول حدث في الـ Webhook. الحدث الذي لا يستقبله الـ Webhook يجيب بـ 400 event_not_subscribed.
{"event": "reply.positive", "delivery_id": "9012", "created_at": "2026-11-07T09:30:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00", "test": true}}التحقق من التوقيع
التوقيع هو HMAC-SHA256 للجسم الخام باستخدام السر الخاص بك. قارنه قبل أن تثق في الاستدعاء. استخدم بايتات الجسم كما وصلت تمامًا، قبل أي تحليل لـ JSON.
import hmac, hashlib
def is_from_argorant(secret: str, raw_body: bytes, signature_header: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header)const crypto = require("crypto");
function isFromArgorant(secret, rawBody, signatureHeader) {
const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"));
const given = Buffer.from(signatureHeader || "");
return given.length === expected.length && crypto.timingSafeEqual(expected, given);
}يحتوي الجسم الموقّع على delivery_id وcreated_at، فلا يمكن تغيير أي منهما دون كسر التوقيع. احتفظ بمعرّفات التسليم التي عالجتها وتجاوز أي معرّف رأيته من قبل. هذا يجعل الاستدعاء المُعاد إرساله بلا ضرر.
عندما يكون خادمك متوقفًا
يُعاد الاستدعاء الذي يفشل بعد دقيقة واحدة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 6 ساعات، أي حتى 6 مرات. تبقى X-Argorant-Delivery نفسها في كل محاولة للحدث الواحد، لذا استخدمها لتجاوز الأحداث التي عالجتها بالفعل. بعد 50 استدعاءً فاشلًا متتاليًا يُوقف تفعيل الـ Webhook، فأعد تفعيله باستخدام PATCH و"active": true. لا يُحتسب الرد 404: يُعاد الاستدعاء كما ورد أعلاه، ولا يُوقف تفعيل الـ Webhook إلا عندما يجيب عنوانك بـ 404 لمدة 7 أيام دون أن يصل أي استدعاء. يعني 410 Gone أن العنوان زال نهائيًا، فيُحذف الـ Webhook فورًا، وأضفه مرة أخرى عندما تريد عودة الاستدعاءات.
وسوم صندوق البريد
ضع وسومًا على صناديق البريد الجديدة عند طلبها، وضع وسومًا أو تواقيع على مئات صناديق البريد الحالية في خطوة واحدة، مثل كل صناديق البريد في طلب واحد.
أرسل الأشخاص إلى أدواتك الأخرى
أرسل عملية تصدير إلى أداة الإرسال التي تستخدمها بالفعل، في حسابك الخاص هناك. تُرسل القائمة في صورة عملية التصدير الخاصة بها. متاح بدءًا من خطة Pro.