Webhook'lar

Webhook, bir üretim son durumuna ulaştığında Morphic'in çağırdığı, size ait bir HTTPS uç noktasıdır. Teslimatlar imzalanır, yaklaşık bir gün boyunca yeniden denenir ve günlüğe kaydedilir. Her olay yalın bir bildirimdir: hangi üretimin bittiğini ve nasıl bittiğini söyler; varlıkları, faturalandırması ve hata mesajı için üretimi anahtarınızla okursunuz.

Bir uç nokta kaydedinCopy Anchor Link

POST /v1/direct/webhooks, generations:write kapsamını gerektirir.

curl -s https://mcp.morphic.com/v1/direct/webhooks \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://hooks.example.com/morphic",
        "events": ["generation.succeeded", "generation.failed", "generation.cancelled"],
        "description": "Production order pipeline"
      }'

Yanıt 201 olur:

{
  "webhook": {
    "id": "01929a10-0c3d-7f44-8a21-0b1c2d3e4f50",
    "url": "https://hooks.example.com/morphic",
    "events": ["generation.succeeded", "generation.failed", "generation.cancelled"],
    "description": "Production order pipeline",
    "created_at": "2026-10-25T08:00:00.000Z",
    "signing_secret": "whsec_4b1e…"
  }
}

• signing_secret yalnızca bu yanıtta gösterilir. API anahtarını sakladığınız gibi saklayın.
• Gizli anahtarı yenilemek için yeni bir uç nokta kaydedin, çağrılarınızı onun kimliğine geçirin, ardından eskisini silin.
• Bir kuruluş en fazla 10 uç nokta tutabilir.

Uç noktaları yönetinCopy Anchor Link

Bir çağrıya uç nokta ekleyinCopy Anchor Link

Araç çağrısının gövdesinde webhook_id iletin. O çağrının başlattığı her üretim, uç noktanın abone olduğu bir son duruma ulaştığında o uç noktaya teslim edilir. webhook_id içermeyen çağrılar webhook göndermez.

Videoyu Morphic'in sunucularında render eden araçlar (video_compose, video_* dönüşümleri ve burn_subtitles) henüz webhook_id kabul etmez; üretimlerini yoklayın.

Olay türleriCopy Anchor Link

• Her üretim en fazla bir olay oluşturur.
• queued ve in_progress teslim edilmez; bunlara ihtiyacınız varsa yoklama yapın.
• Bir üretim, başladıktan sonra 72 saat boyunca izlenir. Daha geç biten bir üretim olay göndermez, bu yüzden onu okuyun.

TeslimatCopy Anchor Link

POST /morphic HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: Morphic-Webhooks/1.0
Morphic-Event-Id: 0192a7c0-5d4e-7b3a-8c2d-1e0f9a8b7c6d
Morphic-Delivery-Id: 0192a7c0-6e5f-7c4b-9d3e-2f1a0b9c8d7e
Morphic-Event-Type: generation.succeeded
Morphic-Signature: t=1792919741,v1=5f8a0c…e21b

{
  "id": "0192a7c0-5d4e-7b3a-8c2d-1e0f9a8b7c6d",
  "type": "generation.succeeded",
  "created_at": "2026-10-25T09:15:42.410Z",
  "api_version": "v1",
  "data": {
    "generation": {
      "object": "generation",
      "id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
      "tool": "generate_video",
      "status": "succeeded",
      "completed_at": "2026-10-25T09:15:41.902Z",
      "error_code": null,
      "metadata": { "order_id": "4411" }
    }
  }
}

data.generation yalnızca şu alanları taşır:

Bir olay hiçbir zaman çıktıları, bağlantıları, faturalandırmayı, modeli veya hata mesajını taşımaz; böylece yanlış yere ya da bir günlüğe düşen bir teslimat hiçbir şey açığa çıkarmaz. Olayı aldığınızda üretimi anahtarınızla okuyun: GET /v1/direct/generations/{id} veya birden fazlası için toplu okuma. Bir olay gönderildiğinde faturalandırmasında artık hiçbir değişiklik beklenmez, dolayısıyla bu okuma kesindir.

Bir olay genellikle üretim son durumuna ulaştıktan sonra yaklaşık bir dakika içinde gönderilir. Gerçek zamanlı bir akış değildir: beklediğiniz tek bir üretimde en düşük gecikme için onu uzun yoklamayla izleyin.

İmzayı doğrulayınCopy Anchor Link

v1, {t}.{raw request body} dizesinin, uç noktanızın signing_secret değeriyle anahtarlanmış onaltılık HMAC-SHA256 değeridir.

1. Başlığı , karakterinden t ve v1 olarak bölün.
2. HMAC_SHA256(secret, t + "." + raw_body) değerini, herhangi bir JSON ayrıştırması veya yeniden serileştirmeden önce, aldığınız ham baytlar üzerinden hesaplayın.
3. Sabit zamanlı bir karşılaştırmayla v1 ile karşılaştırın.
4. Tekrar saldırılarını önlemek için t şu andan 5 dakikadan fazla uzaksa teslimatı reddedin.

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/morphic', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('Morphic-Signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', process.env.MORPHIC_WEBHOOK_SECRET)
    .update(`${parts.t}.${req.body}`)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  const valid =
    parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));

  if (!fresh || !valid) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  enqueue(event); // process asynchronously, keyed by event.id
  res.sendStatus(204);
});

Yanıt verme ve yeniden denemelerCopy Anchor Link

• 10 saniye içinde herhangi bir 2xx ile yanıt verin, işi ondan sonra yapın.
• Diğer her şey başarısız bir denemedir: 2xx olmayan bir durum, zaman aşımı, reddedilen bağlantı, TLS hatası.
• Yönlendirmeler izlenmez; bir 3xx başarısız bir denemedir.
• Sıra garanti edilmez ve bir olay birden fazla kez gelebilir. İşleyicinizi Morphic-Event-Id veya bir üretimin en fazla bir olayı olduğundan data.generation.id üzerinde idempotent yapın.

Başarısız bir deneme şu sürelerden sonra yeniden denenir:

Yedinci yeniden denemeden sonra, yani ilk denemeden yaklaşık 22 saat sonra, olaydan vazgeçilir. Üretimin kendisi bundan etkilenmez: onu GET /v1/direct/generations/{id} ile okuyun.

Teslimat günlüğüCopy Anchor Link

GET /v1/direct/webhooks/{webhook_id}/events (assets:read kapsamı), uç nokta için en son 20 olayı, her biri gönderilen gövdenin tam haliyle ve her denemenin sonucuyla birlikte döndürür. Tek bir üretimin olayları için ?generation_id=… ekleyin.

{
  "webhook_events": [
    {
      "id": "0192a7c0-5d4e-…",
      "type": "generation.succeeded",
      "generation_id": "0192a7b3-…",
      "status": "delivered",
      "created_at": "2026-10-25T09:15:42.410Z",
      "payload": { "…": "the body that was sent" },
      "attempts": [
        { "id": "0192a7c0-6e5f-…", "attempted_at": "2026-10-25T09:15:42.900Z", "response_status": 204, "duration_ms": 131, "error": null, "response_body_excerpt": null }
      ]
    }
  ]
}

Herhangi bir sorun yaşarsanız ya da sorularınız olursa, bizimle iletişime geçmekten çekinmeyin. Yardım etmeye memnuniyet duyarız. Bize şu adresten yazın: support@morphic.com.