Créer une automatisation par webhook - Weights & Biases Documentation

Cette page explique comment créer une automatisation webhook, qui envoie une requête HTTP à un service externe lorsqu’un événement spécifique se produit dans W&B. Utilisez une automatisation webhook pour intégrer W&B à des systèmes externes tels que des pipelines CI/CD, des services de notification ou des outils personnalisés. Pour créer une automatisation Slack, veuillez plutôt vous référer à Créer une automatisation Slack. Dans les grandes lignes, pour créer une automatisation webhook, suivez ces étapes :

Si nécessaire, créez un secret W&B pour chaque valeur sensible requise par l’automatisation, comme un jeton d’accès, un mot de passe ou une clé SSH. Les secrets sont définis dans vos Team Settings.
Créez un webhook pour définir le point de terminaison et les détails d’autorisation, et accordez à l’intégration l’accès à tous les secrets dont elle a besoin.
Créez l’automatisation pour définir l’événement à surveiller et la charge utile que W&B envoie. Accordez à l’automatisation l’accès à tous les secrets dont elle a besoin pour la charge utile.

Créer un webhook

Un administrateur de l’équipe peut ajouter un webhook à l’équipe. Le webhook définit le point de terminaison vers lequel W&B envoie les requêtes, ainsi que les identifiants requis pour s’y authentifier.

Si le webhook nécessite un Bearer token ou si sa charge utile nécessite une chaîne sensible, créez un secret qui le contient avant de créer le webhook. Vous pouvez configurer au maximum un jeton d’accès et un autre secret par webhook. Le service du webhook détermine les exigences d’authentification et d’autorisation de votre webhook.

Connectez-vous à W&B, puis accédez à la page Team Settings.
Dans la section Webhooks, cliquez sur New webhook.
Saisissez un nom pour le webhook.
Saisissez l’URL du point de terminaison du webhook.
Si le webhook nécessite un Bearer token, définissez Access token sur le secret qui le contient. Lorsque vous utilisez l’automatisation webhook, W&B définit l’en-tête HTTP Authorization: Bearer sur le jeton d’accès, et vous pouvez accéder au jeton dans la variable de charge utile ${ACCESS_TOKEN}. Pour plus d’informations sur la structure de la requête POST que W&B envoie au service de webhook, voir dépanner votre webhook.
Si le webhook nécessite un mot de passe ou une autre chaîne sensible dans sa charge utile, définissez Secret sur le secret qui la contient. Lorsque vous configurez l’automatisation qui utilise le webhook, vous pouvez accéder au secret comme variable de charge utile en préfixant son nom par $. Si le jeton d’accès du webhook est stocké dans un secret, vous devez également effectuer l’étape suivante pour indiquer ce secret comme jeton d’accès.
Pour vérifier que W&B peut se connecter au point de terminaison et s’y authentifier :
1. Facultatif : fournissez une charge utile de test. Pour faire référence à un secret auquel le webhook a accès dans la charge utile, préfixez son nom par $. W&B utilise cette charge utile uniquement pour les tests et ne l’enregistre pas. Vous configurez la charge utile d’une automatisation lorsque vous créez l’automatisation. Pour plus d’informations sur l’emplacement du secret et du jeton d’accès dans la requête POST, voir dépanner votre webhook.
2. Cliquez sur Test. W&B tente de se connecter au point de terminaison du webhook à l’aide des identifiants que vous avez configurés. Si vous avez fourni une charge utile, W&B l’envoie.
Si le test échoue, vérifiez la configuration du webhook et réessayez. Si nécessaire, reportez-vous à dépanner votre webhook.

Capture d’écran montrant deux webhooks dans une équipe

Vous pouvez maintenant créer une automatisation qui utilise le webhook.

Créer une automatisation

Après avoir configuré un webhook, créez une automatisation qui définit quel événement W&B déclenche le webhook et quelle charge utile envoyer. Sélectionnez Registry ou Project selon la portée souhaitée, puis suivez ces étapes pour créer une automatisation qui déclenche le webhook.

Registry
projet

Un administrateur du Registry peut créer des automatisations dans ce registre. Les automatisations au niveau du registre s’appliquent à toutes les collections du registre, y compris celles qui seront ajoutées ultérieurement.

Connectez-vous à W&B.
Cliquez sur le nom d’un registre pour afficher ses détails.
Pour créer une automatisation au niveau du registre, cliquez sur l’onglet Automations, puis sur Create automation.
Choisissez l’événement à surveiller. Renseignez tous les champs supplémentaires qui s’affichent. Par exemple, si vous sélectionnez An artifact alias is added, vous devez spécifier Alias regex. Cliquez sur Next step.
Sélectionnez l’équipe propriétaire du webhook.
Définissez Action type sur Webhooks, puis sélectionnez le webhook à utiliser.
Si vous avez configuré un jeton d’accès pour le webhook, vous pouvez y accéder dans la variable de charge utile ${ACCESS_TOKEN}. Si vous avez configuré un secret pour le webhook, vous pouvez y accéder dans la charge utile en faisant précéder son nom de $. Le service du webhook détermine les exigences de votre webhook.
Cliquez sur Next step.
Indiquez un nom pour l’automatisation. Vous pouvez également fournir une description. Cliquez sur Create automation.

Un administrateur W&B peut créer des automatisations dans un projet.

Connectez-vous à W&B et accédez à la page du projet.
Dans la barre latérale du projet, cliquez sur Automations, puis sur Create automation. Vous pouvez aussi créer rapidement, depuis un graphique en courbes dans le workspace, une automatisation de métrique de run pour la métrique affichée. Survolez le panneau, puis cliquez sur l’icône en forme de cloche en haut du panneau.
Choisissez l’événement à surveiller, par exemple lorsqu’un alias d’artifact est ajouté ou lorsqu’une métrique de run atteint un seuil donné.
1. Renseignez tous les champs supplémentaires qui s’affichent, selon l’événement choisi. Par exemple, si vous sélectionnez An artifact alias is added, vous devez spécifier Alias regex.
  1. Pour les automatisations déclenchées par un run, vous pouvez spécifier un ou plusieurs filtres de run.
    - Filter to one user’s runs : incluez uniquement les runs créés par l’utilisateur spécifié. Cliquez sur le bouton bascule pour activer le filtre, puis indiquez un nom d’utilisateur.
    - Filter on run name : incluez uniquement les runs dont le nom correspond à l’expression régulière indiquée. Cliquez sur le bouton bascule pour activer le filtre, puis indiquez une expression régulière.
  L’automatisation s’applique à toutes les collections du projet, y compris celles qui seront ajoutées ultérieurement.
2. Cliquez sur Next step.
Sélectionnez l’équipe propriétaire du webhook.
Définissez Action type sur Webhooks, puis sélectionnez le webhook à utiliser.
Si votre webhook nécessite une charge utile, construisez-la et collez-la dans le champ Charge utile. Si vous avez configuré un jeton d’accès pour le webhook, vous pouvez y accéder dans la variable de charge utile ${ACCESS_TOKEN}. Si vous avez configuré un secret pour le webhook, vous pouvez y accéder dans la charge utile en faisant précéder son nom de $. Le service du webhook détermine les exigences de votre webhook.
Cliquez sur Next step.
Indiquez un nom pour l’automatisation. Vous pouvez également fournir une description. Cliquez sur Create automation.

Après avoir terminé ces étapes, l’automatisation est active et exécute le webhook chaque fois que l’événement spécifié se produit dans le registre ou le projet.

Afficher et gérer les automatisations

Consultez, modifiez ou supprimez une automatisation depuis l’onglet Automations.

Registry
Project

Gérez les automatisations d’un registre dans l’onglet Automations du registre.

Pour afficher les détails d’une automatisation, cliquez sur son nom.
Pour modifier une automatisation, cliquez sur son menu action (), puis sur Edit automation.
Pour supprimer une automatisation, cliquez sur son menu action (), puis sur Delete automation. W&B vous demande de confirmer.

Référence de la charge utile

Utilisez ces sections pour construire la charge utile de votre webhook. Les sections suivantes décrivent les variables disponibles dans votre charge utile et montrent des exemples de charges utiles pour les services courants. Pour plus de détails sur le test de votre webhook et de sa charge utile, référez-vous à Troubleshoot your webhook.

Variables de charge utile

Le tableau suivant décrit les variables que vous pouvez utiliser pour construire la charge utile de votre webhook.

Variable	Détails
`${project_name}`	Le nom du projet auquel appartient la mutation qui a déclenché l’action.
`${entity_name}`	Le nom de l’entité ou de l’équipe à laquelle appartient la mutation qui a déclenché l’action.
`${event_type}`	Le type d’événement qui a déclenché l’action.
`${event_author}`	L’utilisateur qui a déclenché l’action.
`${alias}`	Contient l’alias d’un artifact si l’automatisation est déclenchée par l’événement Un alias d’artifact est ajouté. Pour les autres automatisations, cette variable est vide.
`${tag}`	Contient les tags d’un artifact si l’automatisation est déclenchée par l’événement Un tag d’artifact est ajouté. Pour les autres automatisations, cette variable est vide.
`${artifact_collection_name}`	Le nom de la collection d’artifacts à laquelle est liée la version d’artifact.
`${artifact_metadata.<KEY>}`	La valeur d’une clé de métadonnées arbitraire de premier niveau de la version d’artifact qui a déclenché l’action. Remplacez `<KEY>` par le nom d’une clé de métadonnées de premier niveau. Seules les clés de métadonnées de premier niveau sont disponibles dans la charge utile du webhook.
`${artifact_version}`	La représentation `Wandb.Artifact` de la version d’artifact qui a déclenché l’action.
`${artifact_version_string}`	La représentation sous forme de `string` de la version d’artifact qui a déclenché l’action.
`${ACCESS_TOKEN}`	La valeur du jeton d’accès configuré dans le webhook, si vous avez configuré un jeton d’accès. W&B le transmet automatiquement dans l’en-tête HTTP `Authorization: Bearer`.
`${SECRET_NAME}`	Si elle est configurée, la valeur d’un secret configuré dans le webhook. Remplacez `SECRET_NAME` par le nom du secret.

Exemples de charges utiles

Les exemples suivants montrent des charges utiles de webhook pour des cas d’usage courants. Les exemples montrent comment utiliser les variables de charge utile.

Déclenchement sur dépôt GitHub
Notification de Microsoft Teams
Notifications Slack

Vérifiez que vos tokens d’accès disposent des autorisations requises pour déclencher votre flux de travail GitHub Actions. Pour plus d’informations, voir la documentation GitHub sur l’événement repository dispatch.

Envoyez un repository dispatch depuis W&B pour déclencher une action GitHub. Par exemple, supposons que vous ayez un fichier de flux de travail GitHub qui utilise un repository dispatch comme déclencheur pour la clé on :

on:
repository_dispatch:
  types: BUILD_AND_DEPLOY

La charge utile du dépôt peut se présenter comme suit :

{
  "event_type": "BUILD_AND_DEPLOY",
  "client_payload":
  {
    "event_author": "${event_author}",
    "artifact_version": "${artifact_version}",
    "artifact_version_string": "${artifact_version_string}",
    "artifact_collection_name": "${artifact_collection_name}",
    "project_name": "${project_name}",
    "entity_name": "${entity_name}"
    }
}

La clé event_type dans la charge utile du webhook doit correspondre au champ types du fichier YAML du flux de travail GitHub.

Le contenu et l’emplacement des chaînes de modèle générées dépendent de l’événement ou de la version du modèle pour lesquels vous avez configuré l’automation. ${event_type} aura pour rendu soit LINK_ARTIFACT, soit ADD_ARTIFACT_ALIAS. Voici un exemple de correspondance :

${event_type} --> "LINK_ARTIFACT" or "ADD_ARTIFACT_ALIAS"
${event_author} --> "<wandb-user>"
${artifact_version} --> "wandb-artifact://_id/QXJ0aWZhY3Q6NTE3ODg5ODg3"
${artifact_version_string} --> "<entity>/model-registry/<registered_model_name>:<alias>"
${artifact_collection_name} --> "<registered_model_name>"
${project_name} --> "model-registry"
${entity_name} --> "<entity>"

Utilisez des chaînes de gabarit pour transmettre dynamiquement le contexte de W&B à GitHub Actions et à d’autres outils. Si ces outils peuvent appeler des scripts Python, ils peuvent utiliser les artifacts de modèle enregistrés via l’API W&B.Pour plus d’informations, voir les ressources suivantes :

Pour plus d’informations sur repository dispatch, consultez la documentation officielle sur GitHub Marketplace.
Regardez les vidéos Webhook Automations for Model Evaluation et Webhook Automations for Model Deployment, qui expliquent comment créer des automatisations pour l’évaluation et le déploiement de modèles.
Consultez le rapport W&B Model CI/CD with W&B, qui montre comment utiliser une automatisation webhook GitHub Actions pour la CI de modèles.
Pour un exemple de CI de modèles avec un webhook Modal Labs, consultez le dépôt GitHub wandb-modal-webhook.

Cet exemple de payload montre comment notifier votre canal Teams au moyen d’un webhook :

{
"@type": "MessageCard",
"@context": "http://schema.org/extensions",
"summary": "New Notification",
"sections": [
  {
    "activityTitle": "Notification from WANDB",
    "text": "This is an example message sent via Teams webhook.",
    "facts": [
      {
        "name": "Author",
        "value": "${event_author}"
      },
      {
        "name": "Event Type",
        "value": "${event_type}"
      }
    ],
    "markdown": true
  }
]
}

Vous pouvez utiliser des template strings pour injecter des données W&B dans votre payload au moment de l’exécution. Voir l’exemple Teams.

Cette section est conservée à titre historique. Si vous utilisez un webhook pour intégrer Slack, W&B vous recommande de mettre à jour votre configuration pour utiliser l’intégration Slack à la place.

Configurez votre application Slack et ajoutez une intégration de webhook entrant en suivant les instructions de la documentation de l’API Slack. Assurez-vous d’utiliser le secret indiqué sous Bot User OAuth Token comme token d’accès de votre webhook W&B.Voici un exemple de payload :

{
    "text": "New alert from WANDB!",
"blocks": [
    {
            "type": "section",
        "text": {
            "type": "mrkdwn",
            "text": "Registry event: ${event_type}"
        }
    },
        {
            "type":"section",
            "text": {
            "type": "mrkdwn",
            "text": "New version: ${artifact_version_string}"
        }
        },
        {
        "type": "divider"
    },
        {
            "type": "section",
        "text": {
            "type": "mrkdwn",
            "text": "Author: ${event_author}"
        }
        }
    ]
}

Dépanner votre webhook

Si un webhook ne fonctionne pas comme prévu, vous pouvez le dépanner de manière interactive avec la W&B App UI ou par programmation à l’aide d’un script shell. Vous pouvez dépanner un webhook lors de sa création ou après coup. Pour plus de détails sur le format utilisé par W&B pour la requête POST, veuillez vous référer à l’onglet Script shell.

W&B App UI
Script shell

Un administrateur de l’équipe peut tester un webhook de manière interactive avec la W&B App UI.

Accédez à la page de votre équipe, puis cliquez sur Settings.
Faites défiler jusqu’à la section Webhooks.
Cliquez sur le menu d’actions () à côté du nom de votre webhook.
Sélectionnez Test.
Dans le panneau de l’UI qui s’affiche, collez votre requête POST dans le champ qui apparaît.
Cliquez sur Test webhook. Dans la W&B App UI, W&B affiche la réponse de votre point de terminaison.

Regardez la vidéo Testing Webhooks in W&B pour voir une démonstration.

Ce script shell montre une méthode pour générer une requête POST similaire à celle que W&B envoie à votre automatisation webhook lorsqu’il est déclenché.Copiez-collez le code ci-dessous dans un script shell pour dépanner votre webhook. Indiquez vos propres valeurs pour :

ACCESS_TOKEN
SECRET
PAYLOAD
API_ENDPOINT

webhook_test.sh

#!/bin/bash

# Votre jeton d’accès et votre secret
ACCESS_TOKEN="your_api_key"
SECRET="your_api_secret"

# URL du point de terminaison de votre webhook
API_ENDPOINT="https://your.webhook.endpoint/path"

# Les données que vous souhaitez envoyer (par exemple, au format JSON)
PAYLOAD='{"key1": "value1", "key2": "value2"}'

# Générez la signature HMAC. Pour des raisons de sécurité, W&B inclut l’en-tête
# X-Wandb-Signature calculé à partir de la charge utile et du secret partagé
# associé au webhook à l’aide de HMAC avec SHA-256.
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# Effectuez la requête cURL
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Wandb-Signature: $SIGNATURE" \
  -d "$PAYLOAD" "$API_ENDPOINT"

​Créer un webhook

​Créer une automatisation

​Afficher et gérer les automatisations

​Référence de la charge utile

​Variables de charge utile

​Exemples de charges utiles

​Dépanner votre webhook

Créer un webhook

Créer une automatisation

Afficher et gérer les automatisations

Référence de la charge utile

Variables de charge utile

Exemples de charges utiles

Dépanner votre webhook