Créer une automatisation par webhook

Créez une automatisation par webhook dans W&B pour envoyer des requêtes HTTP à des services externes lorsque certains événements se produisent.

Cette fonctionnalité nécessite un plan Pro ou Enterprise.

Cette page explique comment créer une automatisation webhook. 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 :

1. 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.
2. Créez un webhook pour définir l’endpoint et les détails d’autorisation, et accordez à l’intégration l’accès à tous les secrets dont elle a besoin.
3. Créez l’automatisation pour définir l’événement à surveiller et la charge utile que W&B enverra. Accordez à l’automatisation l’accès à tous les secrets dont elle a besoin pour la charge utile.

​

Créer un webhook

Un administrateur d’équipe peut ajouter un webhook pour l’équipe.

Si le webhook nécessite un Bearer token ou si sa charge utile requiert 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 pour un webhook. Les exigences d’authentification et d’autorisation de votre webhook sont déterminées par le service de webhook.

1. Connectez-vous à W&B, puis accédez à la page Team Settings.

2. Dans la section Webhooks, cliquez sur New webhook.

3. Saisissez un nom pour le webhook.

4. Saisissez l’URL de l’endpoint du webhook.

5. Si le webhook nécessite un Bearer token, définissez Access token sur le secret qui le contient. Lorsque vous utilisez l’automatisation par webhook, W&B définit l’en-tête HTTP Authorization: Bearer avec le jeton d’accès, et vous pouvez accéder au token dans la variable de charge utile ${ACCESS_TOKEN}. Pour en savoir plus sur la structure de la requête POST que W&B envoie au service de webhook, consultez Troubleshoot your webhook.

6. 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 le contient. Lorsque vous configurez l’automatisation qui utilise le webhook, vous pouvez accéder au secret en tant que variable de charge utile en faisant précéder son nom de $.

   Si le jeton d’accès du webhook est stocké dans un secret, vous devez également effectuer l’étape suivante pour spécifier ce secret comme jeton d’accès.

7. Pour vérifier que W&B peut se connecter à l’endpoint et s’y authentifier :

   1. Si vous le souhaitez, fournissez une charge utile de test. Pour se référer à un secret auquel le webhook a accès dans la charge utile, faites précéder son nom de $. Cette charge utile est utilisée uniquement pour les tests et n’est pas enregistrée. Vous configurez la charge utile d’une automatisation lorsque vous créez l’automatisation. Consultez Troubleshoot your webhook pour voir où le secret et le jeton d’accès sont spécifiés dans la requête POST.
   2. Cliquez sur Test. W&B tente de se connecter à l’endpoint 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 essayez à nouveau. Si nécessaire, consultez Troubleshoot your webhook.

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

​

Créer une automatisation

Après avoir configuré un webhook, sélectionnez registre ou projet, puis suivez ces étapes pour créer une automatisation qui déclenche le webhook.

registre

Un administrateur du registre 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.

1. Connectez-vous à W&B.

2. Cliquez sur le nom d’un registre pour afficher ses détails.

3. Pour créer une automatisation au niveau du registre, cliquez sur l’onglet Automations, puis sur Create automation.

4. 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.

5. Sélectionnez l’équipe propriétaire du webhook.

6. Définissez Action type sur Webhooks, puis sélectionnez le webhook à utiliser.

7. 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 $. Les exigences de votre webhook dépendent du service de webhook.

8. Cliquez sur Next step.

9. Indiquez un nom pour l’automatisation. Vous pouvez également fournir une description. Cliquez sur Create automation.

projet

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

1. Connectez-vous à W&B et accédez à la page du projet.

2. 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.

   

3. 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.

4. Sélectionnez l’équipe propriétaire du webhook.

5. Définissez Action type sur Webhooks, puis sélectionnez le webhook à utiliser.

6. 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 $. Les exigences de votre webhook dépendent du service de webhook.

7. Cliquez sur Next step.

8. Indiquez un nom pour l’automatisation. Vous pouvez également fournir une description. Cliquez sur Create automation.

​

Afficher et gérer les automatisations

Registre

Gérez les automatisations d’un registre depuis 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 d’actions ..., puis sur Modifier l’automatisation.
• Pour supprimer une automatisation, cliquez sur son menu d’actions ..., puis sur Supprimer l’automatisation. Une confirmation est nécessaire.

Projet

Un administrateur W&B peut afficher et gérer les automatisations d’un projet depuis l’onglet Automations du projet.

• Pour afficher les détails d’une automatisation, cliquez sur son nom.
• Pour modifier une automatisation, cliquez sur son menu d’actions ..., puis sur Modifier l’automatisation.
• Pour supprimer une automatisation, cliquez sur son menu d’actions ..., puis sur Supprimer l’automatisation. Une confirmation est nécessaire.

​

Référence de la charge utile

Utilisez ces sections pour construire la charge utile de votre webhook. 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

Cette section 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 un jeton d’accès est configuré. Le jeton d’accès est automatiquement transmis 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

Cette section présente des exemples de charges utiles de webhook pour certains cas d’usage courants. Les exemples montrent comment utiliser les variables de charge utile.

Déclenchement sur dépôt GitHub

Vérifiez que vos tokens d’accès disposent des autorisations requises pour déclencher votre flux de travail GHA. Pour plus d’informations, voir la documentation GitHub.

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 l’automation est configurée. ${event_type} aura pour rendu soit LINK_ARTIFACT, soit ADD_ARTIFACT_ALIAS. Voir ci-dessous 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 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 un rapport W&B, qui montre comment utiliser une automatisation webhook GitHub Actions pour la CI de modèles. Consultez ce dépôt GitHub pour découvrir comment créer une CI de modèles avec un webhook Modal Labs.

Notification de Microsoft Teams

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 (comme indiqué dans l’exemple de Teams ci-dessus).

Notifications Slack

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

Configurez votre application Slack et ajoutez une intégration de webhook entrant en suivant les instructions indiquées dans 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

Dépannez votre webhook de manière interactive avec la W&B App UI ou par programmation à l’aide d’un script Bash. Vous pouvez dépanner un webhook lorsque vous créez un nouveau webhook ou modifiez un webhook existant.

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 Bash.

W&B App UI

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

1. Accédez à la page Team Settings de votre équipe W&B.
2. Faites défiler jusqu’à la section Webhooks.
3. Cliquez sur les trois points horizontaux (icône meatball) à côté du nom de votre webhook.
4. Sélectionnez Test.
5. Dans le panneau de l’UI qui s’affiche, collez votre requête POST dans le champ qui apparaît.
   
6. Cliquez sur Test webhook. Dans la W&B App UI, W&B affiche la réponse de votre Endpoint.
   

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

Script Bash

Ce script shell montre une méthode pour générer une requête POST similaire à celle que W&B envoie à votre automatisation par 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 de votre endpoint de 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ère 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}')

# Effectue 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"