From 1035af7e9fe918d1bff2b9df4b94ff9359b7fcd5 Mon Sep 17 00:00:00 2001 From: Josh Kodroff Date: Mon, 27 Oct 2025 13:31:17 -0400 Subject: [PATCH 1/2] Fix obsolete navigation paths in ESC webhooks documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates navigation instructions to reflect current Pulumi Cloud UI, where organization webhooks are now found under Integrations > Webhooks rather than Settings > Webhooks. Also reorders sections to present environment webhooks before organization webhooks for better logical flow. Additional cleanup includes removing outdated trial callout and screenshot, fixing Python code example syntax errors, correcting grammar errors, and standardizing list formatting per style guide. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- content/docs/esc/environments/webhooks.md | 82 ++++++++++------------- 1 file changed, 36 insertions(+), 46 deletions(-) diff --git a/content/docs/esc/environments/webhooks.md b/content/docs/esc/environments/webhooks.md index 81e7e30703dd..b72bdfcfce21 100644 --- a/content/docs/esc/environments/webhooks.md +++ b/content/docs/esc/environments/webhooks.md @@ -13,11 +13,6 @@ aliases: - /docs/esc/webhooks/ --- -{{% notes "info" %}} -ESC Webhooks is a feature available on the Pulumi Team, Enterprise and Business Critical editions. -To try it out, start a [trial](https://app.pulumi.com/site/trial) now. -{{% /notes %}} - ESC Webhooks allow you to notify external services of events happening within your ESC environments. For example, you can trigger a notification whenever a new revision of an environment is created. @@ -25,24 +20,19 @@ When an event occurs, Pulumi will notify the registered webhook listeners via a request with metadata about the event. The webhook can then be used to emit a notification, start running integration tests, or even update Pulumi stacks. -There are large number of real life applications for webhooks including serving as the foundation -of most _ChatOps_ workflows. - ## Overview -ESC Webhooks can be attached to either an environment or an organization. Environment webhooks -will be notified of events specific to the environment. Organization -webhooks will be notified for events happening within each of the organization's -environments. +ESC Webhooks can be attached to either an environment or a Pulumi Cloud organization: -Organization webhooks can be managed on the Organization Settings page. Environment webhooks can be managed from the webhooks tab on each Environment's detail page. - -![Organization webhooks](/images/docs/reference/service/webhooks/org-webhooks.png) +- **Environment webhooks** will fire in response to events you specify for a single ESC environment. +- **Organization webhooks** can be configured to trigger in response to events you specify for _all_ environments in your Pulumi Cloud organization, in addition to other organization-wide events. +{{% notes "info" %}} Pulumi Cloud also supports webhooks for events related to Pulumi IaC stacks and [Pulumi Deployments](/docs/pulumi-cloud/deployments). For additional information on these types of webhooks, see [Pulumi Cloud Webhooks](/docs/deployments/webhooks). +{{% /notes %}} {{% notes "info" %}} -Webhooks do not guarantee event order. You should not assume events will be received in the order they occurred. +Webhooks do not guarantee ordered delivery of events. That is, you should not assume events will be received in the order in which they occurred. {{% /notes %}} ### Create a Webhook @@ -50,32 +40,32 @@ Webhooks do not guarantee event order. You should not assume events will be rece Pulumi Webhooks may be created through any of the following methods: 1. Manually, in the Pulumi Cloud UI using the steps outlined in [Create an Organization Webhook in the Pulumi Cloud UI](#create-an-organization-webhook-in-the-pulumi-cloud-ui) or [Create an Environment Webhook in Pulumi Cloud in the Pulumi Cloud UI](#create-an-environment-webhook-in-the-pulumi-cloud-ui). -1. Declaratively, as part of a [Pulumi IaC](/docs/iac) program as shown in [Create an Webhook in a Pulumi IaC Program](#create-an-webhook-in-a-pulumi-iac-program) -1. By invoking the [Pulumi Cloud REST API](/docs/pulumi-cloud/cloud-rest-api/#create-webhook) directly. - -#### Create an Organization Webhook in the Pulumi Cloud UI - -1. Navigate to **Settings** > **Webhooks**. -2. Select **Create webhook**. -3. Under Destination, choose **Webhook**, **Slack** or **Microsoft Teams**. - 1. For generic JSON webhooks, provide a display name, payload URL, and optionally a secret. - 2. For Slack webhooks, provide a Slack webhook URL and a display name. - 3. For Microsoft Teams webhooks, provide a Microsoft Teams webhook URL and a display name. -4. Choose which events you would like to receive using groups and filters menu. +1. Declaratively, as part of a [Pulumi IaC](/docs/iac) program as shown in [Create a Webhook in a Pulumi IaC Program](#create-a-webhook-in-a-pulumi-iac-program) +1. By invoking the [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/webhooks/#create-webhook) directly. #### Create an Environment Webhook in the Pulumi Cloud UI -1. Navigate to your environment. -2. Navigate to **Webhooks** tab. -3. Select **Create webhook**. -4. Under Destination, choose **Webhook**, **Slack**, **Microsoft Teams** or **Deployment** +1. Navigate to the environment you wish to create a webhook for. +1. Navigate to **Webhooks** tab. +1. Select **Create webhook**. +1. Under Destination, choose **Webhook**, **Slack**, **Microsoft Teams** or **Deployment** 1. For generic JSON webhooks, provide a display name, payload URL, and optionally a secret. - 2. For Slack webhooks, provide a Slack webhook URL and a display name. - 3. For Microsoft Teams webhooks, provide a Microsoft Teams webhook URL and a display name. - 4. For Deployment webhooks, provide the stack to deploy in the format `project/stack`. -5. Choose which events you would like to receive using groups and filters menu. + 1. For Slack webhooks, provide a Slack webhook URL and a display name. + 1. For Microsoft Teams webhooks, provide a Microsoft Teams webhook URL and a display name. + 1. For Deployment webhooks, provide the stack to deploy in the format `project/stack`. +1. Choose which events you would like to receive using groups and filters menu. + +#### Create an Organization Webhook in the Pulumi Cloud UI + +1. In the main Pulumi Cloud navigation, select **Integrations** > **Webhooks**. +1. Select **Create webhook**. +1. Under Destination, choose **Webhook**, **Slack** or **Microsoft Teams**. + 1. For generic JSON webhooks, provide a display name, payload URL, and optionally a secret. + 1. For Slack webhooks, provide a Slack webhook URL and a display name. + 1. For Microsoft Teams webhooks, provide a Microsoft Teams webhook URL and a display name. +1. Choose which events you would like to receive using groups and filters menu. -#### Create an Webhook in a Pulumi IaC Program +#### Create a Webhook in a Pulumi IaC Program The following example shows how to create an Environment webhook in a Pulumi IaC program by declaring a [Webhook resource](/registry/packages/pulumiservice/api-docs/webhook/) with the [Pulumi Cloud provider](/registry/packages/pulumiservice). @@ -101,13 +91,13 @@ const webhook = new pulumiservice.Webhook("example-webhook", { ```python import pulumi -import pulumi_pulumiservice -webhook = pulumi_service.Webhook("example-webhook", - active: True, - display_name: "webhook example", - organization_name: "example", - environmentName: "my-environment", - payload_url: "https://example.com/webhook", +import pulumi_pulumiservice as pcloud +webhook = pcloud.Webhook("example-webhook", + active=True, + display_name="webhook example", + organization_name="example", + environment_name="my-environment", + payload_url="https://example.com/webhook" ) ``` @@ -419,5 +409,5 @@ func computeSignature(payload []byte, secret string) string { ## Additional Resources -* [Managing Github Webhooks with Pulumi](/blog/managing-github-webhooks-with-pulumi/) -* [Pulumi Cloud REST API](/docs/pulumi-cloud/cloud-rest-api/) +- [Managing Github Webhooks with Pulumi](/blog/managing-github-webhooks-with-pulumi/) +- [Pulumi Cloud REST API](/docs/pulumi-cloud/cloud-rest-api/) From 9594bb67fd62a65e1b9eabf7f933e7bd5e5c2154 Mon Sep 17 00:00:00 2001 From: Josh Kodroff Date: Tue, 28 Oct 2025 13:58:56 -0400 Subject: [PATCH 2/2] Add admin permission requirement and fix navigation path for organization webhooks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses PR feedback by documenting that organization webhook creation requires admin permissions and correcting the navigation path to Settings > Integrations > Webhooks. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- content/docs/esc/environments/webhooks.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/docs/esc/environments/webhooks.md b/content/docs/esc/environments/webhooks.md index b72bdfcfce21..27d490ffee0e 100644 --- a/content/docs/esc/environments/webhooks.md +++ b/content/docs/esc/environments/webhooks.md @@ -57,7 +57,11 @@ Pulumi Webhooks may be created through any of the following methods: #### Create an Organization Webhook in the Pulumi Cloud UI -1. In the main Pulumi Cloud navigation, select **Integrations** > **Webhooks**. +{{% notes "info" %}} +You must be an admin of the organization to create organization webhooks. +{{% /notes %}} + +1. Select **Settings** > **Integrations** > **Webhooks**. 1. Select **Create webhook**. 1. Under Destination, choose **Webhook**, **Slack** or **Microsoft Teams**. 1. For generic JSON webhooks, provide a display name, payload URL, and optionally a secret.