Webhooks

Bir uç noktayı bir kez kaydedin, ardından onun webhook_id bir çalıştırma başlattığınızda ve 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": "hikâye hattı"
}

Gerektirir runs:write. URL herkese açık olmalıdır https içinde kimlik bilgileri olmadan; bir kuruluş en fazla 10 uç nokta tutar.

Bu 201 yanıt, uç noktanın id — bunu şu olarak iletin: webhook_id bir çalıştırmada — ve onun imzalama sırrı (whsec_…), yalnızca bir kez gösterilir. 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 }
  }
}

Bu çalıştırma nesne aynı yapıya sahiptir Bir workflow çalıştırmasını oku döndürür, varlıklar dahil edilir — 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

Şunun bir HMAC-SHA256'sını hesaplayın: {timestamp}.{ham gövde} imzalama sırrınızla ve bunu şuna karşılaştırın: v1 sabit zamanda. Şunu kullanın: ham gövdeyi, herhangi bir JSON ayrıştırmasından önce.

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;

  // Yeniden oynatılan bir teslimatı reddedin.
  return Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

Yeniden denemeler ve sıralamaCopy Anchor Link

• Yanıt 2xx içinde 10 saniye. Önce onaylayın, sonra işi yapın — yavaş bir işleyici başarısızlık olarak algılanır.
• Bir olmayan2xx 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 ulaşabilir sırasız ve birden fazla kez. Anahtar olarak Morphic-Event-Id ve daha önce işlediğinizi yok sayın.
• Bir başarılı 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.