Trigger a pipeline with a webhook

This topic describes how to trigger a pipeline with a webhook.

Prerequisites

You can enable the webhook trigger to automate pipeline runs. This streamlines pipeline jobs and facilitates seamless integration and efficient deployment.

On the pipeline configuration page, click the trigger settings tab and turn on the webhook trigger switch. The page then displays the URLs for the general webhook and pipeline source webhook. Click the copy icon next to the desired URL. Then, in the upper-right corner, click save only or save and run to complete the configuration.

Important

To run a pipeline using a webhook trigger, ensure the webhook trigger switch is turned on. Webhook triggers are typically used for calls from third-party tools outside of your code source, but you can also configure them for your own systems.

Method 1: General webhook trigger

After enabling the webhook trigger for a pipeline, run the following command to trigger it:

curl --header "Content-Type: application/json" --request POST --data "{}" http://flow-openapi.aliyun.com/pipeline/webhook/your-webhook

Method 2: Pipeline source webhook trigger

The URL for the pipeline source webhook trigger is the same as that for the code source trigger. You can choose the configuration that best fits your use case.

Method 3: Environment variable webhook trigger

Webhook triggers support environment variables. You can trigger a pipeline using its variables' default values, or you can override them in the run command. The procedure is as follows:

On the pipeline editing page, select the variables and cache tab. In the left-side pane, select variables and add an environment variable in the string variable section.

To trigger the pipeline and override an environment variable's default value, include the new value in the request data.

curl --header "Content-Type: application/json" --request POST --data "{\"abc\":\"456\"}" http://flow-openapi.aliyun.com/pipeline/webhook/your-webhook

In the example, the environment variable abc has a default value of 123 before the pipeline is triggered. After the trigger, the pipeline prints the variable's value as 456.

[executionStep begins at 2024-10-12 14:19:25]
##################################################################
    # name      : Command
    # version   : v1.0.69
    # description : execute shell command
    # help url  : https://atomgit.com/flow-step/Command.git
    # build id  : f097ed94-f9fa-40cc-a34a-64741c07ed4a
##################################################################
2024-10-12 14:19:25 [INFO] Given shell executor: [] useGivenShell: [false]
2024-10-12 14:19:25 [INFO] Invoke script with shell [bash]
2024-10-12 14:19:25 [INFO] ------ User Command Content ------
# input your command here
echo ${abc}
2024-10-12 14:19:25 [INFO] ------ User Command Content ------
2024-10-12 14:19:25 [INFO] 456
2024-10-12 14:19:25 [SUCCESS] run step successfully!

You can use these methods to trigger pipelines from any third-party system.

FAQ

Webhook trigger fails with "permission denied"

A webhook-triggered pipeline runs with the permissions of the user who last enabled the trigger. If that user lacks the necessary permissions or their permissions have been revoked, the trigger will fail. Follow these steps to update the permissions:

Disable the webhook trigger.
Have a user with sufficient permissions to run the pipeline re-enable the webhook trigger.
Send the webhook request again to verify the fix.