Webhooks

Registriere einen Endpunkt einmal und übergib dann seine webhook_id wenn du einen Run startest, und wir benachrichtigen dich, wenn dieser Run zu einem von dir abonnierten Zustand wechselt — normalerweise innerhalb einer Minute.

Endpunkt registrierenCopy Anchor Link

POST {base_url}/webhooks

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

Erfordert runs:write. Die URL muss öffentlich https ohne Anmeldedaten darin; eine Organisation hält bis zu 10 Endpunkte.

Die 201 Antwort enthält die ID — übergib sie als webhook_id bei einem Run — und ihr Signaturgeheimnis (whsec_…), nur einmal angezeigt. Speichere es so, wie du den API-Schlüssel speichern würdest.

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

GET (runs:read) listet deine Endpunkte, niemals deren Geheimnisse. DELETE (runs:write) entfernt einen; für ihn noch ausstehende Zustellungen werden verworfen. Um ein Geheimnis zu rotieren, registriere einen neuen Endpunkt und verschiebe deine Runs dorthin.

EreignisseCopy Anchor Link

Die ZustellungCopy 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 }
  }
}

Die Run hat dieselbe Struktur Einen Workflow-Run lesen gibt zurück, Assets enthalten — daher benötigt eine erfolgreich zugestellte Nachricht keinen Folgeaufruf. Es ist der Run, so wie er war, als das Ereignis ausgelöst wurde, und seine Asset-Links bleiben etwa einen Tag lang gültig, solange die Zustellungs-Wiederholungen laufen.

Jede Zustellung verifizierenCopy Anchor Link

Berechne ein HMAC-SHA256 von {timestamp}.{raw body} mit deinem Signaturgeheimnis und vergleiche es mit v1 in konstanter Zeit. Verwende den rohen Body, bevor irgendein JSON-Parsing stattfindet.

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;

  // Eine wiederholte Zustellung ablehnen.
  return Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

Wiederholungen und ReihenfolgeCopy Anchor Link

• Antworte 2xx innerhalb von 10 Sekunden. Bestätige zuerst, dann erledige die Arbeit — ein langsamer Handler gilt als Fehlschlag.
• Ein Nicht-2xx oder ein Timeout wird etwa einen Tag lang mit exponentiellem Backoff erneut versucht, dann verworfen. Eine Weiterleitung wird nicht verfolgt und zählt als Fehlschlag.
• Es werden nur die Ereignisse gesendet, für die ein Endpunkt abonniert ist; ein Run, der einen anderen Zustand erreicht, meldet dafür nichts.
• Zustellungen können eintreffen in falscher Reihenfolge und mehr als einmal. Verwende als Schlüssel Morphic-Event-Id und ignoriere eine, die du bereits verarbeitet hast.
• Eine erfolgreiche Zustellung kann eintreffen, bevor dein eigener Eintrag des Runs existiert. Behandle das entsprechend, statt einen Fehler auszulösen — oder weiche für diese Runs auf Polling aus.