خطافات الويب

سجّل نقطة نهاية مرة واحدة، ثم مرّر معرّف webhook عندما تبدأ تشغيلًا، وسنتواصل معك عندما تتغير تلك العملية إلى حالة اشتركت فيها — عادةً خلال دقيقة.

سجّل نقطة نهايةCopy Anchor Link

POST {base_url}/webhooks

{
  "url": "https://hooks.example.com/morphic",
  "events": ["workflow_run.succeeded", "workflow_run.failed"],
  "description": "خط أنابيب القصة"
}

يتطلب runs:write. يجب أن يكون عنوان URL عامًا https من دون أي بيانات اعتماد فيه؛ تحتفظ المؤسسة بما يصل إلى 10 نقاط نهاية.

الاستجابة 201 تتضمن معرّف نقطة النهاية المعرّف — مرّره كـ معرّف webhook في عملية تشغيل — و السرّ الخاص بالتوقيع (whsec_…)، ويُعرض مرة واحدة. خزّنه كما تفعل مع مفتاح API.

GET {base_url}/webhooks
DELETE {base_url}/webhooks/{webhook_id}

GET (runs:read) يسرد نقاط النهاية الخاصة بك، وليس أسرارها أبدًا. DELETE (runs:write) يزيل واحدة؛ أي عمليات تسليم لا تزال معلقة لها تُسقَط. لتدوير سرّ، سجّل نقطة نهاية جديدة وانقل عمليات التشغيل إليها.

الأحداثCopy Anchor Link

عملية التسليمCopy Anchor Link

POST https://hooks.example.com/morphic
Morphic-Event-Id: 0192f4a0-3c71-7b92-8e14-5d6f2a9b3c07
Morphic-Delivery-Id: 0192f4a0-4d82-7c03-9f25-6e7a3b0c4d18
Morphic-Event-Type: workflow_run.succeeded
Morphic-Signature: t=1790056632,v1=3f9c1a…

{
  "id": "0192f4a0-3c71-7b92-8e14-5d6f2a9b3c07",
  "type": "workflow_run.succeeded",
  "created_at": "2026-09-22T04:17:12Z",
  "api_version": "v1",
  "data": {
    "run": { "id": "0192f3d0-…", "status": "succeeded", "assets": [], "credits_used": 1792 }
  }
}

الاستجابة التشغيل الكائن له البنية نفسها اقرأ عملية تشغيل سير عمل يُرجع، الأصول مضمَّنة — لذا لا تحتاج عملية تسليم ناجحة إلى استدعاء متابعة. إنها العملية كما كانت عند إطلاق الحدث، وتبقى روابط أصولها صالحة لمدة يوم تقريبًا، طالما استمرت محاولات إعادة تسليمها.

تحقّق من كل عملية تسليمCopy Anchor Link

احسب HMAC-SHA256 لـ {timestamp}.{raw body} باستخدام سرّ التوقيع الخاص بك وقارنه مع v1 بوقت ثابت. استخدم الخام الهيئة، قبل أي تحليل JSON.

import crypto from 'node:crypto';

function verify({ rawBody, header, secret }) {
  const parts = Object.fromEntries(
    header.split(',').map((pair) => pair.split('=')),
  );

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const signed = Buffer.from(expected);
  const given = Buffer.from(parts.v1);

  if (signed.length !== given.length) return false;
  if (!crypto.timingSafeEqual(signed, given)) return false;

  // ارفض عملية تسليم معادة.
  return Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

إعادة المحاولة والترتيبCopy Anchor Link

• استجابة 2xx خلال 10 ثوانٍ. أقرّ أولًا، ثم أنجز العمل — فالمعالج البطيء يُعامَل على أنه فشل.
• غير-2xx أو انتهاء المهلة تتم إعادة المحاولة لها مع تراجع أسي لمدة يوم تقريبًا، ثم تُسقَط. لا يُتبع أي تحويل، ويُحتسب فشلًا.
• لا تُرسَل إلا الأحداث التي اشتركت فيها نقطة نهاية؛ فعملية تشغيل تصل إلى حالة أخرى لا تُبلّغ عنها شيئًا.
• يمكن أن تصل عمليات التسليم خارج الترتيب وأكثر من مرة. اربطها بـ Morphic-Event-Id وتجاهل أيًا منها عالجته بالفعل.
• عملية تسليم ناجحة يمكن أن تصل عملية تسليم قبل أن يوجد سجلك الخاص بالعملية. تعامل مع ذلك بدلًا من إصدار خطأ — أو ارجع إلى الاستقصاء الدوري لهذه العمليات.