Webhooks

Bir uç noktayı bir kez kaydedin, ardından bir çalıştırma başlatırken onun webhook_id değerini iletin; o çalıştırma abone olduğunuz bir duruma geçtiğinde sizi ararız — genellikle bir dakika içinde.

Bir uç noktayı kaydedinCopy Anchor Link

POST {base_url}/webhooks

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

runs:write gerektirir. URL, içinde kimlik bilgisi olmayan herkese açık bir https adresi olmalıdır; bir kuruluş en fazla 10 uç nokta tutar.

201 yanıtı, uç noktanın id değerini — bunu bir çalıştırmada webhook_id olarak iletin — ve yalnızca bir kez gösterilen imzalama sırrını (whsec_…) taşır. Bunu API anahtarını saklar gibi saklayın.

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

GET (runs:read) uç noktalarınızı listeler, sırlarını asla değil. DELETE (runs:write) birini kaldırır; onun için hâlâ bekleyen teslimatlar düşürülür. Bir sırrı döndürmek için yeni bir uç nokta kaydedin ve çalıştırmalarınızı ona taşıyın.

OlaylarCopy Anchor Link

TeslimatCopy 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 nesnesi, Bir workflow çalıştırmasını oku sayfasının döndürdüğüyle aynı yapıdadır, assets dahil — bu nedenle başarılı bir teslimat ek bir çağrı gerektirmez. O, olay tetiklendiğinde çalıştırmanın o anki hâlidir ve teslimatın yeniden denemeleri sürdüğü sürece varlık bağlantıları yaklaşık bir gün boyunca geçerli kalır.

Her teslimatı doğrulayınCopy Anchor Link

İmzalama sırrınızla {timestamp}.{raw body} için bir HMAC-SHA256 hesaplayın ve bunu sabit zamanda v1 ile karşılaştırın. Herhangi bir JSON ayrıştırmasından önce ham gövdeyi kullanın.

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;
}

Yeniden denemeler ve sıralamaCopy Anchor Link

• 10 saniye içinde 2xx ile yanıt verin. Önce onaylayın, sonra işi yapın — yavaş bir işleyici başarısızlık olarak algılanır.
• 2xx olmayan bir yanıt veya zaman aşımı, yaklaşık bir gün boyunca üstel geri çekilme ile yeniden denenir, sonra düşürülür. Bir yönlendirme izlenmez ve başarısızlık sayılır.
• Yalnızca bir uç noktanın abone olduğu olaylar gönderilir; başka bir duruma ulaşan bir çalıştırma bunun için hiçbir şey bildirmez.
• Teslimatlar sırasız ve birden fazla kez ulaşabilir. Anahtar olarak Morphic-Event-Id kullanın ve daha önce işlediğinizi yok sayın.
• Bir succeeded teslimat, çalıştırmanın kendi kaydınız oluşmadan önce ulaşabilir. Hata vermek yerine bunu ele alın — ya da o çalıştırmalar için sorgulamaya geri dönün.