Webhook

Daftarkan endpoint sekali, lalu teruskan miliknya webhook_id 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": "alur cerita"
}

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

Sebuah 201 respons menyertakan milik endpoint id — 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 }
  }
}

Sebuah run objeknya memiliki bentuk yang sama Baca workflow run mengembalikan, aset disertakan — jadi pengiriman yang berhasil tidak memerlukan panggilan lanjutan. Itu adalah run sebagaimana adanya saat peristiwa dipicu, dan tautan 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 mentah isi body, 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;

  // Tolak pengiriman yang diputar ulang.
  return Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

Percobaan ulang dan pengurutanCopy Anchor Link

• Jawaban 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 dan abaikan yang sudah Anda tangani.
• Sebuah berhasil pengiriman dapat tiba sebelum catatan run Anda sendiri ada. Tangani itu daripada menghasilkan error — atau beralih ke polling untuk run tersebut.