Delen via

definitie resources.webhooks.webhook

  • Artikel

Met een webhookresource kunt u uw pijplijn integreren met een externe service om de werkstroom te automatiseren.

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.

Definities die naar deze definitie verwijzen: resources.webhooks

Eigenschappen

webhook Tekenreeks. Vereist als eerste eigenschap.
Naam van de webhook. Acceptabele waarden: [-_A-Za-z0-9]*.

connection Tekenreeks. Vereist.
Naam van de verbinding. In het geval van een offline webhook is dit het type binnenkomende webhook, anders is dit het type van de webhook-extensie.

type Tekenreeks.
Naam van de webhook-extensie. Laat dit leeg als het een offline webhook is.

filtersresources.webhooks.webhook.filters.
Lijst met triggerfilters.

Voorbeelden

Basisvoorbeeld

U kunt uw pijplijn als volgt definiëren.

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

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

Als u uw pijplijn wilt activeren met behulp van de webhook, moet u een POST aanvraag indienen bij https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/<webhook_connection_name>?api-version=6.0-preview. Dit eindpunt is openbaar beschikbaar en er is geen autorisatie nodig. De aanvraag moet de volgende hoofdtekst hebben.

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

Wanneer u gegevens opent vanuit de aanvraagbody van de webhook, moet u er rekening mee houden dat dit kan leiden tot een onjuiste YAML. Als in de vorige pijplijn uw stap bijvoorbeeld wordt gelezen - script: echo ${{ parameters.WebHook.resource.message }}en u de pijplijn activeert via een webhook, wordt de pijplijn niet uitgevoerd. Dit komt doordat tijdens het vervangen door ${{ parameters.WebHook.resource.message.title }}message, dat de volgende JSON bevat, de gegenereerde YAML ongeldig wordt.

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

Omdat de gegenereerde YAML ongeldig wordt, wordt er geen pijplijnuitvoering in de wachtrij geplaatst als reactie.

Niet-geautoriseerde pijplijnuitvoeringen voorkomen

Met webhooks kan iedereen uw pijplijn activeren, zolang ze de namen van uw organisatie en webhookserviceverbinding kennen.

U kunt onbevoegde pijplijnuitvoeringen voorkomen door een geheim te definiëren bij het maken van een binnenkomende webhookserviceverbinding. U moet ook de naam opgeven van de HTTP-header die de SHA-1-controlesom van de hoofdtekst van de webhook bevat.

Om te controleren of een binnenkomende webhook REST API-aanroep is geautoriseerd, berekent Azure Pipelines de SHA-1-controlesom van de hoofdtekst van de aanvraag met behulp van het geheim als sleutel. Vervolgens wordt deze vergeleken met de controlesom die in de aanvraagheader is doorgegeven. Op deze manier bewijst de beller dat hij het geheim kent.

We kijken naar een voorbeeld. Stel dat u een inkomende webhookserviceverbinding hebt geconfigureerd met de naam IncomingWH, hebt opgegeven dat het geheim is secreten dat de controlesom wordt verzonden in de HTTP-header met de naam X-WH-Checksum. Stel dat u een pijplijn hebt die een webhookresource definieert.

Stel dat u de pijplijn wilt activeren met behulp van de volgende aanvraagbody:

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

Hiervoor moet u een POST aanvraag indienen bij https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/IncomingWH?api-version=6.0-preview en de X-WH-Checksum header toevoegen met de waarde van 750D33212D3AD4932CC390819050734831A0A94F. U hoeft geen gebruikersnaam & wachtwoord of een ander type verificatiegegevens op te geven.

Azure Pipelines berekent onafhankelijk de SHA-1-controlesom van de hoofdtekst met behulp van secret als sleutel en genereert dezelfde 750D33212D3AD4932CC390819050734831A0A94F waarde. Omdat de waarden overeenkomen, wordt de aanroep geautoriseerd en wordt de pijplijnwachtrij voortgezet.

U berekent de waarde van de X-WH-Checksum header, in pseudocode, als SHA1(secret).ComputeHash(requestBody). U kunt gebruiken. System.Security.Cryptography.HMACSHA1 De net-klasse voor dit doeleinde.

Om validatiefouten als gevolg van nieuwe regels of witruimten te voorkomen, raden we u aan de hoofdtekst in een geminimaliseerde vorm te verzenden. Dat wil, verzenden

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

In plaats van

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

Hoewel de twee bovenstaande JSON-objecten hetzelfde object vertegenwoordigen, genereren ze verschillende SHA-1-controlesommen. Dit komt doordat SHA-1 wordt berekend op basis van de tekenreeksweergave, die anders is.

Zie ook