External Automation Using Webhook-Based Approvals

When you should use webhook-based approvals

You can think of webhook-based approvals as a generic extensibility layer that enables you to call any API in any internet-accessible system. You can use a webhook to obtain a decision from a process that is external to Armory CD-as-a-Service.

Webhook use cases

Before deployment

• Upgrade a database schema
• Custom approval process

Within your deployment strategy

• Check logs and system health
• Run custom tests

After deployment

• Run integration tests in a staging environment
• Perform metric tests
• Run security scanners

How webhook-based approval works

In order to accommodate a long-running process, Armory CD-as-a-Service supports the asynchronous webhook with callback pattern. You define the webhook in your deployment file and add a webhook call in the constraints section of your deployment definition or in a canary step.

Basic flow

The deployment process:

1. Encounters a webhook call
2. Calls the external API
3. Pauses deployment while waiting for the callback
4. Receives and processes callback
   • Success: deployment proceeds
   • Failure: deployment rolls back

flowchart TB   
   A --> B
   B --> C
   C --> D
   D --> E
   E --> F
   F -- "Success: true" --> G
   F -- "Success: false" --> H

   A["Deployment Starts"]
   B["Webhook Call Triggered<br>Deployment Pauses"]
   F{"Did the external process<br>succeed or fail?"}
   G["Deployment Continues"]
   H["Deployment Rolls Back"]

   subgraph exp [External Process]
   C["External API<br>Receives Request"]
   D["Process Runs"]
   E[Callback to Deployment]
   end

Requirements for your webhook and callback

• The webhook must retrieve the callback URI from the payload or query parameters.
• The callback must use Bearer authorization and include a success value and optional message in the body.

Retrieve an OAUTH token to use in your callback

Request format:

curl --request POST \
  --url https://auth.cloud.armory.io/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'data=audience=https://api.cloud.armory.io&grant_type=client_credentials&client_id=$CDAAS_CLIENT_ID&client_secret=$CDAAS_CLIENT_SECRET'

Example response:

{
  "access_token": "<very long access token>",
  "scope": "manage:deploy read:infra:data exec:infra:op read:artifacts:data",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Callback format

curl --request POST \
  --url 'https://$CALLBACK_URI' \
  --header 'Authorization: Bearer $OAUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"success": true, "mdMessage": "Webhook successful"}'

Armory CD-as-a-Service looks for success value of true or false to determine the webhook’s success or failure. mdMessage should contain a user-friendly message for Armory CD-as-a-Service to display in the UI and write to logs.

What’s next

• Configure a Webhook in the Deployment File

Last modified August 5, 2022: (f8573d7c)