resources.webhooks.webhook definition

  • Artikel

Mit einer Webhookressource können Sie Ihre Pipeline in einen externen Dienst integrieren, um den Workflow zu automatisieren.

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.

Definitionen, die auf diese Definition verweisen: resources.webhooks

Eigenschaften

webhook Schnur. Erforderlich als erste Eigenschaft.
Name des Webhooks. Zulässige Werte: [-_A-Za-z0-9]*.

connection Schnur. Erforderlich.
Name der Verbindung. Im Fall eines Offline-Webhooks ist dies der Typ des eingehenden Webhooks, andernfalls handelt es sich um den Typ der Webhookerweiterung.

type Schnur.
Name der Webhookerweiterung. Lassen Sie diese leer, wenn es sich um einen Offline-Webhook handelt.

filtersresources.webhooks.webhook.filters.
Liste der Triggerfilter.

Beispiele

Einfaches Beispiel

Sie können Ihre Pipeline wie folgt definieren.

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

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

Um Ihre Pipeline mithilfe des Webhooks auszulösen, müssen Sie eine POST-Anforderung an https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/<webhook_connection_name>?api-version=6.0-preview senden. Dieser Endpunkt ist öffentlich verfügbar, und es ist keine Autorisierung erforderlich. Die Anforderung sollte den folgenden Text aufweisen.

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

Wenn Sie auf Daten über den Anforderungstext des Webhooks zugreifen, sollten Sie beachten, dass dies möglicherweise zu einem falschen YAML-Code führen kann. Wenn beispielsweise in der vorherigen Pipeline Ihr Schritt - script: echo ${{ parameters.WebHook.resource.message }} lautet, und Sie die Pipeline über einen Webhook auslösen, wird die Pipeline nicht ausgeführt. Dies liegt daran, dass beim Ersetzen von ${{ parameters.WebHook.resource.message.title }} durch den Code message, der den folgenden JSON-Code enthält, der generierte YAML-Code ungültig wird.

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

Da der generierte YAML-Code ungültig wird, wird als Reaktion keine Pipelineausführung in die Warteschlange eingereiht.

Verhindern nicht autorisierter Pipelineausführungen

Webhooks ermöglichen es jedem, Ihre Pipeline auszulösen, solange sie die Namen Ihrer organization- und Webhookdienstverbindung kennt.

Sie können nicht autorisierte Pipelineausführungen verhindern, indem Sie beim Erstellen einer eingehenden Webhookdienstverbindung ein Geheimnis definieren. Sie müssen auch den Namen des HTTP-Headers angeben, der die SHA-1-Prüfsumme des Webhookskörpers enthält.

Um zu überprüfen, ob ein eingehender Webhook-REST-API-Aufruf autorisiert ist, berechnet Azure Pipelines die SHA-1-Prüfsumme des Anforderungstexts mithilfe des Geheimnisses als Schlüssel. Anschließend wird sie mit der Prüfsumme verglichen, die im Anforderungsheader übergeben wurde. Auf diese Weise beweist der Anrufer, dass er das Geheimnis kennt.

Schauen wir uns ein Beispiel an. Angenommen, Sie haben eine eingehende Webhookdienstverbindung namens IncomingWHkonfiguriert, haben angegeben, dass das Geheimnis ist secretund dass die Prüfsumme im HTTP-Header mit dem Namen X-WH-Checksumgesendet wird. Stellen Sie sich vor, Sie verfügen über eine Pipeline, die eine Webhookressource definiert.

Angenommen, Sie möchten die Pipeline mithilfe des folgenden Anforderungstexts auslösen:

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

Dazu müssen Sie eine POST Anforderung an https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/IncomingWH?api-version=6.0-preview stellen und den X-WH-Checksum Header mit dem Wert hinzufügen 750D33212D3AD4932CC390819050734831A0A94F. Sie müssen keinen Benutzernamen & Kennwort oder andere Authentifizierungsinformationen angeben.

Azure Pipelines berechnet unabhängig die SHA-1-Prüfsumme des Textkörpers mithilfe secret des Schlüssels und generiert denselben 750D33212D3AD4932CC390819050734831A0A94F Wert. Da die Werte übereinstimmen, wird der Aufruf autorisiert, und die Pipelinewarteschlange wird fortgesetzt.

Sie berechnen den Wert des X-WH-Checksum Headers in Pseudocode als SHA1(secret).ComputeHash(requestBody). Sie können verwenden. Die NET-Klasse System.Security.Cryptography.HMACSHA1 für diesen Zweck.

Um Validierungsfehler aufgrund neuer Zeilen oder Leerzeichen zu verhindern, empfehlen wir, den Text in minimierter Form zu senden. Das heißt, senden

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

anstelle von

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

Obwohl die beiden obigen JSON-Objekte dasselbe Objekt darstellen, generieren sie unterschiedliche SHA-1-Prüfsummen. Dies liegt daran, dass SHA-1 für ihre Zeichenfolgendarstellung berechnet wird, die sich unterscheidet.

Weitere Informationen