Webhook

Daftarkan endpoint sekali, lalu teruskan webhook_id miliknya saat Anda memulai sebuah run dan kami menghubungi Anda ketika run tersebut berubah ke state yang Anda langgani — biasanya dalam satu menit.

Daftarkan endpointCopy Anchor Link

POST {base_url}/webhooks

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

Memerlukan runs:write. URL harus berupa https publik tanpa kredensial di dalamnya; sebuah organisasi menampung hingga 10 endpoint.

Respons 201 menyertakan id milik endpoint — teruskan sebagai webhook_id pada sebuah run — dan rahasia penandatanganan (whsec_…), ditampilkan sekali. Simpan seperti Anda menyimpan kunci API.

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

GET (runs:read) mencantumkan endpoint Anda, tidak pernah rahasianya. DELETE (runs:write) menghapus salah satunya; pengiriman yang masih tertunda untuknya akan dibuang. Untuk mengganti rahasia, daftarkan endpoint baru dan pindahkan run Anda ke sana.

PeristiwaCopy Anchor Link

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

Objek run memiliki bentuk yang sama dengan yang dikembalikan Baca run alur kerja, termasuk assets — jadi pengiriman yang berhasil tidak memerlukan panggilan lanjutan. Itu adalah run sebagaimana adanya saat peristiwa dipicu, dan link asetnya tetap valid selama sekitar satu hari, selama percobaan ulang pengiriman.

Verifikasi setiap pengirimanCopy Anchor Link

Hitung HMAC-SHA256 dari {timestamp}.{raw body} dengan rahasia penandatanganan Anda dan bandingkan dengan v1 dalam waktu konstan. Gunakan isi body mentah, sebelum parsing JSON apa pun.

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

Percobaan ulang dan pengurutanCopy Anchor Link

• Jawab dengan 2xx dalam 10 detik. Konfirmasi dulu, lalu kerjakan — handler yang lambat dianggap sebagai kegagalan.
• Sebuah non-2xx atau timeout dicoba ulang dengan exponential backoff selama sekitar satu hari, lalu dibuang. Redirect tidak diikuti, dan dihitung sebagai kegagalan.
• Hanya peristiwa yang dilanggan endpoint yang dikirim; run yang mencapai state lain tidak melaporkan apa pun untuknya.
• Pengiriman dapat tiba tidak berurutan dan lebih dari sekali. Gunakan Morphic-Event-Id sebagai kunci dan abaikan yang sudah Anda tangani.
• Pengiriman succeeded dapat tiba sebelum catatan run Anda sendiri ada. Tangani itu daripada menghasilkan error — atau beralih ke polling untuk run tersebut.