خطافات الويب

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

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

POST {base_url}/webhooks

{
  "url": "https://hooks.example.com/morphic",
  "events": ["workflow_run.succeeded", "workflow_run.failed"],
  "description": "story pipeline"
}

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

الاستجابة 201 تتضمن معرّف نقطة النهاية id — مرّره كـ webhook_id في عملية تشغيل — و السرّ الخاص بالتوقيع (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 }
  }
}

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

تحقّق من كل عملية تسليم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;

  // Refuse a replayed delivery.
  return Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

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

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