Webhooks الأتمتة: الصادرة والواردة وتوقيعاتها

إجراء الإرسال إلى تطبيق آخر في الأتمتة يوقّع كل طلب بسر خاص بكل أتمتة. ومشغّل إرسال بيانات من تطبيق آخر يمنحك رابطاً عاماً يقبل JSON حتى 64 كيلوبايت، مع توقيع اختياري.

7 دقائقحُدّث 27‏/10‏/2026

افتح في كورتيكسا

الصادر: إجراء الإرسال إلى تطبيق آخر

يُضبط من إجراءات الأتمتة. الطلب يحمل هذه الترويسات:

الترويسة

المعنى

X-Workflow-Signature

sha256= + HMAC للجسم الخام

X-Workflow-Timestamp

وقت التوقيع بثواني يونكس

X-Workflow-Signature-V2

sha256= + HMAC لـtimestamp.rawBody (مفضّل)

X-Corteksa-Payload-Version

1 أو 2 لشكل الجسم التلقائي

Idempotency-Key

ثابت لكل محاولات نفس الخطوة في نفس التشغيل

السر خاص بكل أتمتة، ويبدأ بـwhsec_. التطبيق لا يعرضه، فللتحقق من الطلبات في نظامك أضف ترويسة خاصة بك تحت الترويسات في الخطوة، مثل مفتاح ينتظره نظامك.

شكل الجسم

المحتوى

الإصدار 2 (الافتراضي للخطوات الجديدة)

الحقول بمعرّفاتها، والخيارات { id, label }، والمسؤولون بمعرّفاتهم، وevent_id لمنع التكرار

الإصدار 1 (قديم)

الشكل القديم بالأرقام الداخلية

مخصص

قالب JSON بمتغيرات، بلا إصدار

التسليم: مهلة 10 ثوانٍ، لا تتبع التحويلات، أي 2xx نجاح. تُعاد المحاولة عند 5xx و408 و425 و429 وانقطاع الشبكة حتى 5 محاولات، بفاصل يبدأ 5 ثوانٍ ويتضاعف حتى 10 دقائق. التسليم «مرة على الأقل»، فامنع التكرار بـIdempotency-Key.

العناوين الداخلية والخاصة مرفوضة. حتى 20 ترويسة مخصصة، وكل قيمة حتى 2048 حرفاً.

الوارد: إرسال بيانات من تطبيق آخر

مشغّل في الأتمتة يمنح رابطاً عاماً POST /api/v1/workflow-hooks/{token}.

البند

القاعدة

الجسم

كائن JSON بنوع application/json حتى 64 كيلوبايت

التوقيع (اختياري)

X-Corteksa-Timestamp خلال 5 دقائق، وX-Corteksa-Signature: v1=<HMAC(secret, timestamp.rawBody)>

منع التكرار

Idempotency-Key لمدة يوم، أو نفس الجسم خلال 10 دقائق

المعدل

60 طلباً في الدقيقة

الاستماع للتجربة

10 دقائق يُلتقط فيها الطلب التالي كعيّنة دون تشغيل

الرد

202 مع request_id وduplicate

اضغط إضافة مفتاح توقيع لتفعيل التوقيع: يظهر السر مرة واحدة، وبعدها يجب توقيع كل طلب. فقدته؟ اضغط إنشاء مفتاح جديد. وإيقاف التحقق يوقف التوقيع.

إذا حدثت مشكلة

ما تراه

السبب

الحل

401 BAD_SIGNATURE

توقيع خطأ أو وقت قديم.

وقّع على timestamp.rawBody بالسر الحالي.

409 WORKFLOW_OFF

الأتمتة متوقفة.

شغّلها.

413 BODY_TOO_LARGE

الجسم أكبر من 64 كيلوبايت.

قلّص البيانات.

415 BODY_NOT_JSON_OBJECT

الجسم ليس كائن JSON.

أرسل كائناً بنوع JSON.

429 HOOK_RATE_LIMITED

تجاوزت المعدل.

انتظر حسب Retry-After، وقلّل الطلبات.

429 WORKFLOW_RUNS_USED_UP

نفدت تنفيذات الأتمتة الشهرية.

اشترِ حزمة. راجع اشترِ إضافة أو حزمة رصيد.

404 HOOK_NOT_FOUND

الرابط خطأ.

انسخ العنوان من جديد من مشغّل الأتمتة.

قواعد يجب معرفتها

حجم العيّنة الملتقطة حتى 16 كيلوبايت.

آخر وقت استقبال يُحدّث مرة في الدقيقة على الأكثر.

هل حلّ هذا الدليل مشكلتك؟

إن لم يحلها، سنسألك عمّا كان ناقصاً.

قد تحتاج بعد ذلك