Webhook Trigger

Webhooks are HTTP endpoints that allow external systems to trigger pipeline runs. When an external service sends an HTTP request to the webhook URL, it automatically starts the configured pipeline, enabling seamless integration with third-party tools and services.

Configuring Webhooks in Pipeline

To configure a webhook in Pipeline, go to the Workflow tab when creating a new pipeline.
In the TRIGGERS section, click the + icon, then select Webhook from the dropdown menu.

Image loading... Selecting Webhook trigger in TRIGGERS Pipeline section

After selecting the webhook trigger, in the Settings tab you can configure basic webhook settings:

Image loading... Webhook settings with URL, token and TOTP options

Webhook URL - unique webhook address with authorization token. The token can be regenerated if needed.

Time-based one-time password (TOTP) - optional security feature requiring a 6-digit code generated in real-time.

Every request triggers a run to the branch's HEAD revision by default. Pipeline runs can be customized using URL query or POST parameters.

Generating TOTP Code

Replace <GENERATED_TOTP> with your Base32 secret key from webhook settings.

Bash:

bash
apt install -y oathtool

# Generate token (6-digit TOTP)
oathtool --totp --base32 "<GENERATED_TOTP>"
$$$$

JavaScript:

js
import { TOTP } from 'otpauth';
      
const totp = new TOTP({ secret: '<GENERATED_TOTP>' });
      
// Generate token (6-digit TOTP)
const code = totp.generate();
console.log(code);

Python:

python
import pyotp

secret_base32 = "<GENERATED_TOTP>"

# Generate token (6-digit TOTP)
totp = pyotp.TOTP(secret_base32)
print(totp.now())

Webhook Parameters

Image loading... List of available webhook parameters with types and examples

Parameter	Type and Example
`branch` Sets run branch	Type: String Example: `master`
`clear_cache` Clears cache before run	Type: Boolean Example: `true`
`comment` Sets run comment	Type: String Example: `My first webhook run`
`environment` Sets run environment	Type: String Example: `my-env`
`from_scratch` Ignores last run commit	Type: Boolean Example: `true`
`priority` Sets run priority	Type: String Example: `HIGH`
`pull_request` Sets run pull request	Type: String Example: `pr/12`
`revision` Sets run commit	Type: String Example: `b9e511d1287e2e11015ef4191f4917c14c79301c`
`tag` Sets run tag	Type: String Example: `1.2.3`
`vars.my_variable` Sets run variable	Type: String Example: `my_value`

Usage Examples

Image loading... HTTP GET and POST examples with webhook parameters

HTTP GET with query parameters

http
GET
https://app.buddy.works/buddy/project/pipelines/pipeline/124660/webhook?revision=b9e511d1287e2e11015ef4191f4917c14c79301c&environment=my-env&from_scratch=true&clear_cache=true&comment=My%20first%20webhook%20run&priority=HIGH&vars.my_variable=my_value&token=bud_wh_us_nymezzivt04bhd9x6fdntq7nb41d6a

HTTP POST with parameters in request body

javascript
POST
https://app.buddy.works/buddy/project/pipelines/pipeline/124660/webhook?token=bud_wh_us_nymezzivt04bhd9x6fdntq7nb41d6a
{
  "revision": "b9e511d1287e2e11015ef4191f4917c14c79301c",
  "environment": "my-env",
  "from_scratch": "true",
  "clear_cache": "true",
  "comment": "My first webhook run",
  "priority": "HIGH",
  "vars": {
    "my_variable": "my_value"
  }
}

Hint

Additional Resources:

Event schema - YAML event schema documentation
API Create Webhook - API event schema documentation

FAQ

Can a webhook trigger a pipeline on a specific code version?
Yes, use the revision parameter with commit hash.

How to secure webhook against unauthorized access?
Enable TOTP in webhook settings and use token in every request.

Can I pass custom environment variables?
Yes, use the vars.variable_name parameter in request.

What are the available run priorities?
Available priorities are: HIGH, NORMAL, LOW. Use the priority parameter to set the desired priority.

Does webhook work with wildcard pipeline?
Yes, use branch or tag parameters to specify the exact branch/tag.

How to generate a new webhook token?
In webhook settings, click Regenerate token.

Can I generate a new TOTP key?
Yes, in webhook settings you can generate a new TOTP key when needed.

How to enable legacy webhooks?
Go to Workspace Settings → Workspace tab → WEBHOOKS section and check "Legacy webhooks enabled" to use the legacy webhook system. This setting can only be changed by workspace owners and administrators.

Image loading... Legacy webhooks checkbox in Workspace Settings

Last modified on Oct 1, 2025

On git event Manual trigger