Webhook

Le bloc Webhook génère un point de terminaison HTTP unique. Tout service externe capable d'envoyer une requête HTTP POST peut déclencher votre workflow.

Fonctionnement

1. Ajoutez un bloc Webhook à votre workflow.
2. Une URL de webhook unique est générée pour ce bloc — copiez-la depuis le champ Lien de déclenchement du bloc.
3. Configurez votre service externe (GitHub, Stripe, tout système personnalisé) pour envoyer un POST à cette URL.
4. Lorsque la requête arrive, le workflow démarre et le corps de la requête, les en-têtes, la méthode et les paramètres de requête sont injectés comme sorties du bloc.

L'éditeur enregistre le webhook une fois que les modifications en attente ont fini d'être sauvegardées. Tant que le serveur n'a pas confirmé l'enregistrement, le Lien de déclenchement reste vide au lieu d'afficher une URL fictive. Si l'enregistrement échoue, le bloc affiche une erreur avec une action permettant de réessayer. Les webhooks gérés par un déclencheur font partie du cycle de vie du bloc ; supprimez le bloc déclencheur plutôt que son webhook séparément.

Test dans un environnement modifiable

Vous n'avez pas besoin de déployer ou de promouvoir pour tester un webhook. Dans tout environnement modifiable, appeler l'URL de webhook exécute le workflow live/brouillon — exactement ce qui est sur le canvas — afin que vous puissiez itérer et tester de bout en bout pendant la construction.

Dans tout environnement en lecture seule, le webhook exécute le snapshot déployé et nécessite une version de déploiement active. Les noms Développement, Test, Staging et Production sont des conventions choisies par votre organisation, pas des rôles fixes de la plateforme. Chaque environnement possède sa propre URL de webhook. Voir Déclencheurs → Environnements et test pour le modèle complet.

Appel depuis Monitor

Dans Monitor, développez un workflow puis son déclencheur webhook pour afficher la méthode HTTP, le mode d'authentification, le support de l'identifiant et un exemple curl. L'exemple affiché conserve des espaces réservés tels que $WEBHOOK_TOKEN ou $WEBHOOK_SECRET, afin que l'identifiant ne soit jamais rendu sur la page. Dans une expression comme '…?token='"$WEBHOOK_TOKEN", les fragments entre guillemets adjacents constituent une syntaxe shell qui forme un seul argument d'URL ; les guillemets ne font pas partie de l'URL.

Cette surface génère une URL de test et une commande curl exécutable ; elle n'envoie pas une deuxième requête HTTP et n'affiche pas un résultat séparé dans l'éditeur. Exécutez la commande dans votre client HTTP pour voir le corps de réponse canonique. L'exécution est persistée et peut être ouverte dans Monitor via son executionId, y compris après un rechargement.

Lorsque le webhook exige un identifiant configuré, utilisez Copier le jeton du webhook ou Copier le secret HMAC pour copier la valeur effectivement déployée. Utilisez Copier la commande cURL exécutable pour copier une commande complète dans laquelle cette même valeur est déjà insérée. Pour l'authentification par jeton d'URL, Copier l'URL authentifiée copie l'URL complète avec le jeton inséré pour les systèmes qui acceptent uniquement une URL. Scrydon ne récupère l'identifiant qu'après un clic sur l'une de ces actions. Il n'affiche ni ne met en cache sa valeur dans Monitor. Une référence vers un secret d'espace de travail est résolue dans l'espace de travail actuellement affiché dans Monitor.

Toute personne autorisée à voir ce workflow dans Monitor peut utiliser ces actions de copie. Pour modifier ou renouveler l'identifiant, mettez à jour le bloc Webhook source ou le secret d'espace de travail qu'il référence.

Variables disponibles

Référencez la requête entrante dans les blocs en aval en utilisant le nom du bloc comme préfixe :

Remplacez webhook1 par le nom que vous avez donné au bloc.

Authentification

Les points de terminaison des webhooks génériques acceptent uniquement POST. Dans le champ Authentification du bloc, choisissez l'un des modes suivants :

Les nouveaux blocs Webhook utilisent par défaut le mode Jeton Bearer et génèrent automatiquement un jeton. Le corps de la requête est limité à 10 MiB (10 485 760 octets). Une requête plus volumineuse renvoie 413 Payload Too Large et ne démarre pas le workflow.

Chaque URL de webhook possède son propre compartiment de jetons : elle accepte une rafale de 20 requêtes et récupère 10 jetons toutes les 60 secondes. Lorsque ce compartiment est épuisé, Scrydon renvoie 429 Too Many Requests avec un en-tête Retry-After, sans authentifier la requête ni démarrer le workflow. Si l'application de la limite est temporairement indisponible, Scrydon échoue en mode fermé avec 503 Service Unavailable et Retry-After: 5. Le producteur doit attendre l'intervalle indiqué avant de réessayer dans les deux cas.

Jeton d'URL

# Comme paramètre de requête — pour les producteurs qui acceptent uniquement une URL
curl -X POST "https://app.scrydon.com/agentic/api/webhooks/trigger/{path}?token=$WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "orderId": "42"}'

Utilisez une référence vers un secret d'espace de travail telle que {{GENERIC_WEBHOOK_TOKEN}} comme Valeur du jeton, exactement comme pour les autres modes.

Un Paramètre du jeton mal formé est rejeté comme configuration invalide au lieu de revenir silencieusement à la valeur par défaut. Un nom de paramètre qui ne pourrait jamais correspondre à la requête entrante empêcherait toute vérification de l'identifiant alors que la requête serait tout de même signalée comme authentifiée.

Avant d'exposer <webhook1.headers> au workflow, Scrydon masque l'en-tête d'authentification configuré et les en-têtes standards susceptibles de contenir des identifiants, tels que Authorization, Proxy-Authorization, Cookie et Set-Cookie.

Utilisez une référence vers un secret d'espace de travail Scrydon, comme {{GENERIC_WEBHOOK_TOKEN}} pour le Jeton Bearer, la Valeur de l'en-tête ou la Valeur du jeton, ou {{GENERIC_WEBHOOK_HMAC_SECRET}} pour le Secret HMAC. Scrydon résout la référence lors de l'authentification de la requête. Une référence manquante ou indisponible est rejetée.

Jeton Bearer

Le jeton Bearer généré peut être copié depuis Monitor après le déploiement du workflow :

curl -X POST "https://app.scrydon.com/agentic/api/webhooks/trigger/{path}" \
  -H "Authorization: Bearer $WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "orderId": "42"}'

En-tête statique

Par exemple, configurez Nom de l'en-tête sur X-Webhook-Token et Valeur de l'en-tête sur {{GENERIC_WEBHOOK_TOKEN}}, puis envoyez la valeur résolue :

curl -X POST "https://app.scrydon.com/agentic/api/webhooks/trigger/{path}" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: $WEBHOOK_TOKEN" \
  -d '{"event": "order.created", "orderId": "42"}'

Signature HMAC

Scrydon calcule le HMAC sur les octets exacts reçus, avant l'analyse JSON, le décodage du texte, la normalisation ou la resérialisation. Les espaces, l'ordre des propriétés, l'encodage Unicode et un saut de ligne final modifient donc la signature.

Les algorithmes pris en charge sont sha1, sha256 et sha512. Utilisez sha256, sauf si l'appelant nécessite un autre algorithme pris en charge. L'en-tête de signature accepte soit une empreinte hexadécimale seule, soit une empreinte préfixée par l'algorithme :

<hex-digest>
sha256=<hex-digest>

Lorsqu'un préfixe est présent, il doit correspondre à l'algorithme configuré. Les chiffres hexadécimaux sont insensibles à la casse. Cet exemple signe et envoie exactement les octets contenus dans body :

body='{"event":"order.created","orderId":"42"}'
signature="$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | awk '{print $NF}')"

curl -X POST "https://app.scrydon.com/agentic/api/webhooks/trigger/{path}" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=$signature" \
  --data-binary "$body"

Toute erreur d'authentification — en-tête manquant ou incorrect, signature mal formée, configuration invalide ou secret indisponible — renvoie la même réponse et ne démarre pas le workflow :

HTTP/1.1 401 Unauthorized
Content-Type: text/plain; charset=utf-8
Cache-Control: no-store

Unauthorized

Déclencheurs spécifiques aux fournisseurs

Pour les services disposant d'une intégration Scrydon dédiée (GitHub, Microsoft Graph, Atlassian, etc.), préférez le bloc de déclencheur du fournisseur au bloc Webhook générique. Les déclencheurs de fournisseurs analysent et valident automatiquement le payload d'événement et exposent des variables typées.

Voir Fournisseurs pour la liste complète des intégrations avec prise en charge des déclencheurs.

Répondre avec le résultat du workflow

Par défaut, un webhook répond immédiatement avec 200 {"message":"Webhook processed"} et le workflow s'exécute en arrière-plan. Activez Attendre la fin de l'exécution sur le bloc pour répondre avec le résultat :

{ "executionId": "…", "status": "completed", "outputs": { "response": { … } } }

La sortie d'un bloc Response apparaît sous outputs. Si l'exécution dépasse 30 secondes, la requête renvoie 202 avec { "executionId", "status": "running" }. L'exécution se poursuit et l'identifiant permet de la suivre.

Un workflow qui atteint un échec terminal renvoie tout de même HTTP 200, car la requête webhook a été acceptée et le workflow s'est terminé. La réponse contient la raison sûre pour le client :

{
  "executionId": "…",
  "status": "failed",
  "error": {
    "code": "INTEGRATION_ACCOUNT_NOT_WORKSPACE_ENABLED",
    "message": "Ce compte d’intégration n’est pas activé pour cet espace de travail.",
    "retryable": false,
    "blockId": "teams-1"
  }
}

L'authentification, une entrée mal formée et le rejet par la file ou l'infrastructure conservent leurs statuts 4xx/5xx habituels. Une réponse 202 running indique seulement l'expiration du délai de polling synchrone ; consultez ensuite l'état d'exécution ou ouvrez le run dans Monitor pour voir l'erreur terminale persistée. Monitor affiche le même code et message après rechargement et met en évidence le bloc en erreur lorsque blockId est présent.