Configure a Webhook in the Deployment File

Configure a webhook-based approval into your Armory CD-as-a-Service app deployment process.

Before you begin

You have read the External Automation Using Webhook-Based Approvals guide.

How to configure a webhook in your deployment file

In your deployment file, you configure your webhook by adding a top-level webhooks section with the following information:

  - name: <webhook-name>
    method: <endpoint-method-type>
    uriTemplate: <endpoint-uri>
    networkMode: <network-mode>
    agentIdentifier: <remote-network-agent-id>
      - key: Authorization
        value: <auth-type-and-value>
      inline: >-
    retryCount: <num-retries>
  • name: the unique name of your webhook

  • method: (Required) REST API method type of the webhook

  • uriTemplate: (Required) webhook URL; supports placeholders that are replaced at runtime

  • networkMode: (Required) direct or remoteNetworkAgent; direct means a direct connection to the internet; if your webhook is not internet-accessible, use the remoteNetworkAgent as a proxy.

  • agentIdentifier: (Optional) Use when networkMode is remoteNetworkAgent; the Remote Network Agent identifier to use as a proxy; the identifier must match the Agent Identifier value listed on the Agents UI screen; if not specified, Armory CD-as-a-Service uses the Remote Network Agent associated with the environment account.

  • headers: (Optional) Request headers; the Authorization header is required if your webhook requires authorization. Also supports use of context and armory provided variables.

  • bodyTemplate: (Optional) the body of the REST API request; the inline content depends on the endpoint you are calling.

  • retryCount: (Optional; Default: 0) if the first connection attempt fails, the number of retries before failing and declaring that the webhook cannot be reached.

  • disableCallback: (Optional; Default: false) if set to true, Armory CD-as-a-Service does not wait for a callback before moving on to the next deployment step.

Callback URI

You must pass the callback URI as {{armory.callbackUri}}/callback. Armory CD-as-a-Service generates the value for armory.callbackUri and fills it in at runtime.

Webhook context variables

You can use variables in the webhook templates you define in the webhooks block of your deployment for the follow fields: webhooks.[].uriTemplate, webhooks.[].headers, and webhooks.[].bodyTemplate.

Armory-provided context variables

Armory provides the following variables for every webhook execution:

Variable Annotation Environment variable Notes
applicationName ARMORY_APPLICATION_NAME Added as annotation resources and as environment variables on pods*
deploymentId ARMORY_DEPLOYMENT_ID Added as annotation resources and as environment variables on pods*
environmentName ARMORY_ENVIRONMENT_NAME Added as annotation resources and as environment variables on pods*
replicaSetName ARMORY_REPLICA_SET_NAME Added as annotation resources and as environment variables on pods*
accountName - - The name of the account (or agentIdentifier) used to execute the deployment
namespace - - The namespace resources are being deployed to

Prefix the variable with armory and surround with {{}}. For example, to use applicationName, add {{armory.applicationName}} to the webhook query template.

Custom context variables

Add your custom variables to the strategies.<strategyName>.canary.steps.runWebhook.context section of your deployment file:

        - runWebhook:
            name: <webhookName>
              - <variableName>: <variableValue>

You need to configure your custom variables for each webhook step that references them.

In supported webhook fields, you reference them with the following format: {{context.<variableName>}}. For example, if you create a variable called uri for webhooks.[].uriTemplate, you reference it in webhooks.[].bodyTemplate with {{context.uri}}, so that uriTemplate: {{context.uri}} is the address the webhook calls.

Configuration examples

The first example configures a GitHub webhook that uses token authorization, with the token value configured as a Armory CD-as-a-Service secret. This webhook requires the callback URI be passed in the request body. The payload also contains context variables that you pass in when invoking the webhook in your deployment file.

  - name: myWebhook
    method: POST
    networkMode: direct
      - key: Authorization
        value: token {{secrets.github_token}}
      - key: Content-Type
        value: application/json
      inline:  >-
        "event_type": "webhookCallback",
        "client_payload": {
            "callbackUri": "{{armory.callbackUri}}/callback"
            "environment": "{{armory.environmentName}}"
            "applicationName": "{{armory.applicationName}}"
            "replicaSetName": "{{armory.replicaSetName}}"
    retryCount: 3

The second example configures a webhook that is not accessible from the internet. The networkMode is set to remoteNetworkAgent and the agentIdentifier specifies which Remote Network Agent to use. The agentIdentifier value must match the Agent Identifier value listed on the Agents UI screen. The Authorization Bearer value is configured as a Armory CD-as-a-Service secret. Note that in this example, the callback URI is passed in the header.

  - name: integration-tests
    method: POST
    networkMode: remoteNetworkAgent
    agentIdentifier: test-rna
      - key: Authorization
        value: Bearer {{secrets.test_token}}
      - key: Location
        value: {{armory.callbackUri}}/callback
      - key: Content-Type
        value: application/json
      - key: environment
        value: {{context.environment}}
      - key: applicationName
        value: {{armory.applicationName}}
      - key: replicaSetName
        value: {{armory.replicaSetName}}
    retryCount: 5

How to trigger a webhook

You can trigger a webhook from the following areas:

  • Deployment constraints: beforeDeployment and afterDeployment
  • A canary step within a canary strategy
  • The redirectTrafficAfter section of a blue/green strategy

You add a runWebhooks section where you want to trigger the webhook.

- runWebhook:
    name: <webhook-name>
        myCustomKey: myCustomValue
  • name: (Required) webhook name; must match the name you gave your webhook in the webhooks configuration section.
  • context: (Optional) dictionary; declare values to use in templates or headers.

Deployment constraints

Before deployment

In this example, you have a webhook named Update-Database-Schema. You want to trigger this webhook before your app gets deployed. So you trigger the webhook in the beforeDeployment constraint of your environment deployment.

    account: dev-cluster
    namespace: myApp-dev
    strategy: rolling-canary
        - runWebhook:
            name: Update-Database-Schema

App deployment proceeds only if the Update-Database-Schema callback sends a “success: true” message.

After deployment

In this example, you have a webhook named Run-Integration-Tests. You want to trigger this webhook after your app has been deployed to staging but before it gets deployed to production. So you trigger the webhook in the afterDeployment constraint of your staging environment deployment.

    account: staging-cluster
    namespace: myApp-staging
    strategy: rolling-canary
        - runWebhook:
            name: Run-Integration-Tests
              environment: staging
    account: prod-cluster
    namespace: myApp-prod
    strategy: rolling-canary
      dependsOn: ["staging"]

Deployment to production proceeds only if the Run-Integration-Tests callback sends a “success: true” message.

Blue/green strategy

In this example, there is a security-scan webhook that scans your deployed app. You have a blue/green deployment strategy in which you want to run that security scan on the preview version of your app before switching traffic to it. You add the runWebhook section to the redirectTrafficAfter section in your blue/green strategy configuration.

      activeService: myApp-external
      previewService: myApp-preview
        - analysis:
            interval: 7
            units: seconds
            numberOfJudgmentRuns: 1
            rollBackMode: manual
            rollForwardMode: automatic
              - avgCPUUsage-pass
        - runWebhook:
            name: security-scan

Since tasks in the redirectTrafficAfter section run in parallel, both tasks in this example must be successful for deployment to continue. If the analysis task fails, rollback is manual. If the runWebhook task fails, rollback is automatic.

Canary strategy

In this example, there is a system-health webhook that you want to trigger as part of your canary strategy. Add the runWebhook section to your steps configuration.

        - setWeight:
            weight: 25
        - runWebhook:
            name: system-health
              environment: staging

What’s next

Last modified May 1, 2023: (65773341)