Partager via

définition resources.webhooks.webhook

  • Article

Une ressource webhook vous permet d’intégrer votre pipeline à un service externe pour automatiser le workflow.

webhooks:
- webhook: string # Required as first property. Name of the webhook.
  connection: string # Required. Name of the connection. In case of offline webhook this will be the type of Incoming Webhook otherwise it will be the type of the webhook extension.
  type: string # Name of the webhook extension. Leave this empty if it is an offline webhook.
  filters: [ filter ] # List of trigger filters.

Définitions qui font référence à cette définition : resources.webhooks

Propriétés

webhook String. Obligatoire comme première propriété.
Nom du webhook. Valeurs acceptables : [-_A-Za-z0-9]*.

connection String. Obligatoire.
Nom de la connexion. Dans le cas d’un webhook hors connexion, il s’agit du type webhook entrant, sinon, il s’agit du type de l’extension webhook.

type String.
Nom de l’extension webhook. Laissez ce champ vide s’il s’agit d’un webhook hors connexion.

filtersresources.webhooks.webhook.filters.
Liste des filtres de déclencheur.

Exemples

Exemple de base

Vous pouvez définir votre pipeline comme suit.

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

steps:  
- script: echo ${{ parameters.WebHook.resource.message.title }}

Pour déclencher votre pipeline à l’aide du webhook, vous devez faire une POST demande à https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/<webhook_connection_name>?api-version=6.0-preview. Ce point de terminaison est disponible publiquement et aucune autorisation n’est nécessaire. La requête doit avoir le corps suivant.

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

Lorsque vous accédez aux données à partir du corps de la requête du webhook, n’oubliez pas que cela peut entraîner une erreur YAML. Par exemple, si dans le pipeline précédent, votre étape lit - script: echo ${{ parameters.WebHook.resource.message }}et que vous déclenchez le pipeline via un webhook, le pipeline ne s’exécute pas. En effet, dans le processus de remplacement ${{ parameters.WebHook.resource.message.title }} par message, qui contient le JSON suivant, le YAML généré devient non valide.

{
  "title": "Hello, world!",
  "subtitle": "I'm using WebHooks!"
}

Étant donné que le YAML généré ne devient pas valide, aucune exécution de pipeline n’est mise en file d’attente en réponse.

Empêcher les exécutions de pipeline non autorisées

Les webhooks permettent à n’importe qui de déclencher votre pipeline, tant qu’il connaît les noms de votre organization et de votre connexion au service webhook.

Vous pouvez empêcher les exécutions de pipeline non autorisées en définissant un secret lors de la création d’une connexion de service Webhook entrante. Vous devez également spécifier le nom de l’en-tête HTTP qui contient la somme de contrôle SHA-1 du corps du webhook.

Pour vérifier qu’un appel d’API REST de webhook entrant est autorisé, Azure Pipelines calcule la somme de contrôle SHA-1 du corps de la requête à l’aide du secret comme clé. Il le compare ensuite à la somme de contrôle passée dans l’en-tête de requête. De cette façon, l’appelant prouve qu’il connaît le secret.

Prenons un exemple. Supposons que vous avez configuré une connexion de service Webhook entrante nommée IncomingWH, spécifié que le secret est secretet que la somme de contrôle est envoyée dans l’en-tête HTTP nommé X-WH-Checksum. Imaginez que vous disposez d’un pipeline qui définit une ressource Webhook.

Supposons que vous souhaitez déclencher le pipeline à l’aide du corps de la requête suivant :

{"resource":{"message":{"title":"Hello, world!","subtitle":"I'm using WebHooks!"}}}

Pour ce faire, vous devez faire une POST demande à https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/IncomingWH?api-version=6.0-preview et ajouter l’en-tête X-WH-Checksum avec la valeur .750D33212D3AD4932CC390819050734831A0A94F Vous n’avez pas besoin de spécifier de nom d’utilisateur & mot de passe ou tout autre type d’informations d’authentification.

Azure Pipelines calcule indépendamment la somme de contrôle SHA-1 du corps en utilisant secret comme clé et génère la même 750D33212D3AD4932CC390819050734831A0A94F valeur. Étant donné que les valeurs correspondent, l’appel est autorisé et la mise en file d’attente du pipeline se poursuit.

Vous calculez la valeur de l’en-tête X-WH-Checksum , en pseudocode, comme SHA1(secret).ComputeHash(requestBody). Vous pouvez utiliser . Classe de System.Security.Cryptography.HMACSHA1 NET à cet effet.

Pour éviter les échecs de validation dus à de nouvelles lignes ou espaces blancs, nous vous recommandons d’envoyer le corps dans un formulaire réduit. Autrement dit, envoyer

{"resource":{"message":{"title":"Hello, world!","subtitle":"I'm using WebHooks!"}}}

au lieu de

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

Même si les deux objets JSON ci-dessus représentent le même objet, ils génèrent des sommes de contrôle SHA-1 différentes. Cela est dû au fait que SHA-1 est calculé sur leur représentation de chaîne, qui est différente.

Voir aussi