Setup Outgoing Webhook | Copado Essentials Help Center

To enable outgoing webhooks, go to Deploy Options tab, expand the advanced options section and check "Outgoing webhooks" checkbox.

After enabling "Outgoing webhooks", go to the "Outgoing Webhooks" tab and fill in the detail as below.

Both Basic Authentication and the use of custom HTTP request headers are supported.

In the "Payload" section, you can reference the following variables:

$DEPLOYMENT_ID: ID of the deployment, CI Job, or Work Item
$DEPLOYMENT_TITLE: title of the deployment, CI job, or Work Item
$DEPLOYMENT_STATUS: the deployment, CI Job, or Work Item status
$DEPLOYMENT_ACTION: the deployment, CI Job, or Work Item action
$ISSUE_TRACKING_ID: issue ID (JIRA or Azure) associated with the deployment, CI Job, or Work Item
$CURRENT_STAGE: current stage of the work item (this variable is only applied for Work Items)

An Example for Updating Jira Issues

Let's say you want to set up an outgoing webhook to push deployment status updates to Jira and you want to filter the comments so that only successful deployments are posted to Jira, you'll need to follow these steps:

Enable outgoing webhooks:
- Go to the Deploy Options tab
- Expand the advanced options section
- Check the "Outgoing webhooks" checkbox
Set up the webhook:
- Navigate to the "Outgoing Webhooks" tab
- Click on "New" to create a new webhook
Configure the webhook:
- Webhook URL: Enter the Jira API endpoint for creating comments
- Authentication: Select "Basic Auth"
- Username: Your Jira username
- Password: Your Jira API token
Webhook URL format:
https://<your-jira-instance>.atlassian.net/rest/api/2/issue/{issueIdOrKey}/comment

In the "Outgoing Webhooks" tab of your deployment or work item, configure the Jira endpoint by setting the "Webhook URL" to:

https://<your-jira-instance>.atlassian.net/rest/api/2/issue/$ISSUE_TRACKING_ID/comment

Essentials will automatically replace $ISSUE_TRACKING_ID with the actual Jira issue key when the webhook is triggered.

Where:

<your-jira-instance> is the subdomain of your Jira Cloud instance

{issueIdOrKey} is a placeholder that Copado will replace with the actual Jira issue key when sending the webhook

For more detailed information about Jira's REST API endpoints, you can refer to the Jira Cloud REST API documentation.

4. Set up the payload:

In the "Payload" section, you'll want to use conditional logic to only send comments for successful deployments. Here's an example of how you might structure the payload:

{ "body": "Deployment $DEPLOYMENT_ID: $DEPLOYMENT_TITLE completed successfully", "issue": { "key": "$ISSUE_TRACKING_ID" } }

5. Add a condition to the webhook:
NOTE: Copado Essentials plans to release a webhook condition setting in our October 2024 release.

Copado Essentials will replace these variables with the actual deployment values before posting the message to your external service.

When enabled, outgoing webhooks will be triggered following each validation or deployment action, with the exception of scheduling a Pre-Deployment Task. It will be triggered irrespective of whether the action is scheduled or manual.

This Jira-side configuration is a one-time setup. Once you have the API token, you can use it for all your Copado to Jira integrations.

An Example for Updating Azure Boards

You can also set up a similar integration with Azure Boards.

For Azure Boards, the webhook URL format is different from Jira. Here's the general format for Azure Boards:

https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}/comments?api-version=6.0

Where:

{organization} is your Azure DevOps organization name
{project} is your Azure DevOps project name
{id} is a placeholder for the work item ID

In Copado Essentials, you would set up the webhook URL like this:

https://dev.azure.com/{YOUR_ORGANIZATION}/{YOUR_PROJECT}/_apis/wit/workitems/{WORK_ITEM_ID}/comments?api-version=6.0

Replace {YOUR_ORGANIZATION} and {YOUR_PROJECT} with your actual Azure DevOps organization and project names. Leave {WORK_ITEM_ID} as is - Copado Essentials will replace this with the actual work item ID when the webhook is triggered.

For authentication, Azure DevOps uses Personal Access Tokens (PATs). You'll need to generate a PAT in Azure DevOps and use it in the Copado Essentials webhook configuration.

Here's an example of what the payload JSON might look like:

{ "text": "Deployment $DEPLOYMENT_ID ($DEPLOYMENT_TITLE) status: $DEPLOYMENT_STATUS" }

In this payload:

$DEPLOYMENT_ID will be replaced with the actual deployment ID from Copado Essentials
$DEPLOYMENT_TITLE will be replaced with the title of the deployment
$DEPLOYMENT_STATUS will be replaced with the current status of the deployment

You can customize this payload to include more information as needed. For example, you might want to add more details:

{ "text": "Deployment Update:\n- ID: $DEPLOYMENT_ID\n- Title: $DEPLOYMENT_TITLE\n- Status: $DEPLOYMENT_STATUS\n- Action: $DEPLOYMENT_ACTION\n- Current Stage: $CURRENT_STAGE" }

This expanded version includes additional variables that Copado Essentials supports:

$DEPLOYMENT_ACTION: The action performed in the deployment
$CURRENT_STAGE: The current stage of the work item (only applies to Work Items)