ArgorantDocs

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اكتمل فحص بريد إلكتروني واحد باستخدام مفتاح APIemail، 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.resumedcampaign_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

Shell
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الاستدعاءات الأخيرة مع نتيجتها والمحاولة التالية

ما يستلمه خادمك

HTTP
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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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.

JSON
{"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.

Python
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)
Node
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 فورًا، وأضفه مرة أخرى عندما تريد عودة الاستدعاءات.

في هذه الصفحة