Trigger pipelines using custom triggers
Trigger deployments using cURL and Webhooks
This topic shows you how to create and run custom triggers for your Harness pipelines using platform-agnostic Webhooks and cURL commands.
Overview of custom triggers
In addition to triggers that use Git providers, artifact providers, manifests, and cron scheduling, Harness includes custom triggers that you can use to run pipelines via cURL or a platform-agnostic Webhook.
Once you create a custom trigger, Harness provides the Webhook URL and cURL command to initiate the trigger.
You can do the following with a custom trigger:
Start a deployment using a cURL command.
Use a REST call to get deployment status.
Start a deployment using a Webhook URL provided by Harness.
Create the custom trigger
In your Harness pipeline in pipeline studio, click Triggers.
Click New Trigger.
In Webhook, click Custom.
Name the new Trigger and click Continue.
The Payload Type is set as Custom. If this were a Git provider trigger, you would specify the repo URL and events for the trigger.
For more details, go to Trigger Pipelines using Git Events.
Conditions for the custom trigger
Conditions specify criteria in addition to events and actions.
Conditions help to form the overall set of criteria to trigger a Pipeline based on changes in a given source.
For example:
Execute pipeline if the source or target branch name matches a pattern.
Execute pipeline if the event is sent for file changes from specific directories in the Git repository. This is very useful when working with a monorepo (mono repository). It ensures that only specific pipelines are triggered in response to a change.
Conditions support Harness built-in expressions for accessing trigger settings, Git payload data, and headers.
JEXL expressions are also supported.
Conditions are ANDed together (boolean AND operation). All Conditions must match an event payload for it to execute the trigger.
Pipeline input for the custom trigger
Pipelines often have Runtime Inputs like codebase branch names or artifact versions and tags.
Provide values for the inputs. You can use input sets. For more information, go to Passing data in custom triggers.
Select Create Trigger.
The trigger is now added to the Triggers page.
Trigger a deployment using the cURL command for a custom trigger
On the Triggers page, in the Webhook column, select the link icon for your trigger and then select Copy as cURL Command.
Here's an example of the cURL command:
Custom triggers such as Git triggers are part of the pipeline entity and therefore have the account, organization, or project IDs included in the webhook URL.
Run the example command in a terminal to trigger a pipeline execution. The response will look something like this:
The Execution History page shows that the execution was triggered by a custom trigger:
Links in the response from a custom trigger
The JSON response of the custom trigger cURL command contains several links.
The following section describe each link and what you can do with them.
apiUrl parameter in a custom trigger
apiUrl can be used to track deployment status programmatically, such as using a REST call.
For more information, go to Get Deployment Status using REST below.
uiUrl parameter in a custom trigger
The uiUrl from the cURL command output can be used directly in a browser.
To run a deployment from a browser, paste the URL from uiUrl into the browser location field and hit ENTER.
The browser will open app.harness.io and display the running deployment.
uiSetupUrl parameter in a custom trigger
In the JSON response of a Pipeline executed by a custom trigger, the uiSetupUrl label displays the URL or the pipeline that was run.
Get deployment status using REST for a custom trigger
The apiUrl property in the JSON response can be used to track deployment status programmatically, such as using a REST call.
The eventCorrelationId contains the same Id as the URL in apiUrl.To get deployment status using a REST call (in this example, cURL), use the following cURL command, replacing API_URL with the URL from apiUrl:
For example:
The response from the cURL command will contain the status of the deployment. For example:
Passing data in custom triggers
For information on how to pass data in the cURL command for a custom trigger, go to Passing data in Custom triggers.
Custom trigger authorization using API keys
You can use Harness API keys in your cURL command to authorize the execution of a trigger.
You can see the -H 'X-Api-Key: sample_api_key' parameter in the cURL command you copy from Harness.
You can use this parameter with a Harness API key in your cURL command to authorize the execution of a trigger. You can also enforce the use of API keys for all custom triggers.
Adding authorization to custom triggers
Create the Harness API key you want to use for authorization.
Save the token from the key. Please make sure to copy and store your token value somewhere safe. You won't be able to see it again after you create it.
Copy the cURL command for your custom trigger. For example:
Replace
sample_api_keywith the API key you created. For example:Use the cURL command. A
SUCCESSstatus will look something like this:
Enforce authorization for custom triggers
You may Mandate Authorization for Custom Webhook Triggers. Doing this will mandate the use of an API key token in the header of all the custom webhooks in your account. If the setting is turned on, and an API token isn't provided, then the following error will occur:
If RBAC is required on the triggers in your environment, please review the Harness Documentation on enforcing Authorization via RBAC
Executions
My Executions filter on the listing page displays both manual executions and those triggered automatically by custom trigger i.e execution executed by custom trigger/curl command and manually execution pipeline execution will appear in the My Execution list.
But to display execution triggered by custom webhook trigger it must have a authorization i.e X-API-key should be present
Last updated
Was this helpful?