How to add a webhook to one or more projects

You can use webhooks to integrate Upsun into your broader automation chain. Webhooks allow you to trigger actions in external services (like CI/CD pipelines, Slack notifications, or custom APIs) whenever specific events—such as code pushes, environment creations, or deployments—occur on your Upsun environments.

This guide explains how to use the Upsun CLI to add a webhook integration to a single project or roll it out to all of your projects simultaneously.

Prerequisites

• One or more active projects on Upsun.

• The Upsun CLI installed locally and authenticated (upsun login).

Method 1: Adding a webhook to a single project

If you are already inside your local project repository, you can simply run the integration command. Otherwise, you can specify the target project by its ID.

Run the following command, replacing the URL with the endpoint that will receive the POSTed JSON payloads:

upsun integration:add --type=webhook --project=<project-ID> --url=https://example.com/receiver

The CLI will run interactively and prompt you to configure the webhook's behavior:

1. Events to report (--events): Choose what triggers the webhook (e.g., environment.push, environment.branch). Enter * to fire on all events.

2. States to report (--states): Choose when to fire the webhook. Options include pending, in_progress, or complete. Default is complete.

3. Included environments (--environments): Specify which environments should trigger the webhook. Default is * (all environments).

4. Excluded environments (--excluded-environments): Specify any environments that should not trigger the webhook.

Alternatively, you can skip the interactive prompts by passing all arguments inline. This is perfect for automation scripts:

upsun integration:add --type webhook \
  --url https://example.com/receiver \
  --events * \
  --states complete \
  --environments * \
  --excluded-environments ''

Method 2: Adding a webhook to ALL projects at once

If you manage multiple projects and want to apply the exact same webhook configuration to all of them, you can use the upsun multi command combined with a little Bash scripting.

Run the following one-liner in your terminal:

upsun multi -p$(upsun project:list --columns id --pipe | paste -sd "," -) "integration:add --type webhook --url https://example.com/receiver --events * --states complete --environments * --excluded-environments ''"

How this command works:

• upsun project:list --columns id --pipe outputs a clean, newline-separated list of all your project IDs.

• paste -sd "," - reformats that list into a single, comma-separated string (e.g., id1,id2,id3).

• upsun multi -p takes that comma-separated list and executes the provided command (integration:add...) across every project in the list.

Bonus: Adding to projects without existing integrations

What if you only want to add the webhook to projects that don't already have an integration configured?

You can use this more advanced Bash one-liner, which first checks each project for existing integrations and only applies the webhook to the empty ones:

upsun multi -p$(upsun multi -p$(upsun project:list --columns id --pipe | paste -sd "," -) "integration:list --format=csv --no-header" 2>&1 | grep -B1 "No integrations found" | grep -o "\(([[:alnum:]]*)\)$" | cut -c2-14 | paste -sd "," -) "integration:add --type webhook --url https://example.com/receiver --events * --states complete --environments * --excluded-environments ''"

(Note: While these Bash one-liners are incredibly powerful, if you are managing infrastructure at a massive scale, we highly recommend using the Upsun REST API directly for programmatic management instead of relying on Bash tricks!)