Webhooks

Enregistrez un point de terminaison une fois, puis transmettez son webhook_id lorsque vous lancez une exécution, et nous vous appelons lorsque cette exécution passe à un état auquel vous êtes abonné — généralement en moins d’une minute.

Enregistrer un point de terminaisonCopy Anchor Link

POST {base_url}/webhooks

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

Nécessite runs:write. L’URL doit être une URL https publique sans identifiants intégrés ; une organisation peut avoir jusqu’à 10 points de terminaison.

La réponse 201 contient l’id du point de terminaison — transmettez-le comme webhook_id sur une exécution — et son secret de signature (whsec_…), affiché une seule fois. Conservez-le comme vous le feriez pour la clé d’API.

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

GET (runs:read) liste vos points de terminaison, jamais leurs secrets. DELETE (runs:write) en supprime un ; les livraisons encore en attente pour celui-ci sont abandonnées. Pour faire tourner un secret, enregistrez un nouveau point de terminaison et transférez-y vos exécutions.

ÉvénementsCopy Anchor Link

La livraisonCopy 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 }
  }
}

L’objet run a la même structure que celui que renvoie Lire une exécution de workflow, assets inclus — ainsi, une livraison réussie n’a besoin d’aucun appel de suivi. Il s’agit de l’exécution telle qu’elle était au moment où l’événement a été déclenché, et ses liens vers les ressources restent valides pendant environ un jour, tant que les tentatives de livraison continuent.

Vérifiez chaque livraisonCopy Anchor Link

Calculez un HMAC-SHA256 de {timestamp}.{raw body} avec votre secret de signature et comparez-le à v1 en temps constant. Utilisez le corps brut, avant tout parsing JSON.

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

Réessais et ordreCopy Anchor Link

• Répondez 2xx en 10 secondes. Accusez réception d’abord, puis faites le travail — un gestionnaire lent est considéré comme un échec.
• Un non-2xx ou un délai d’attente est réessayé avec un backoff exponentiel pendant environ un jour, puis abandonné. Une redirection n’est pas suivie et est considérée comme un échec.
• Seuls les événements auxquels un point de terminaison est abonné sont envoyés ; une exécution qui atteint un autre état ne signale rien pour celui-ci.
• Les livraisons peuvent arriver dans le désordre et plus d’une fois. Basez-vous sur Morphic-Event-Id et ignorez-en une que vous avez déjà traitée.
• Une livraison succeeded peut arriver avant que votre propre enregistrement de l’exécution n’existe. Gérez cela plutôt que de produire une erreur — ou revenez au sondage pour ces exécutions.