Support

Webhooks

Pulumi Webhooks is a feature available on the Pulumi Team and Enterprise editions.
If you’re keen to try it out, start a Team Edition trial now.

Pulumi Webhooks allow you to notify external services of events
happening within your Pulumi organization or stack. For example,
you can trigger a notification whenever a stack is updated or a team is modified.
Whenever an event occurs, Pulumi will send an HTTP POST request to
all registered webhooks. The webhook can then be used to emit some
notification, start running integration tests, or even update additional stacks.

Webhooks can be used for pretty much anything you want, and are the foundation
of most ChatOps workflows.

Management

Webhooks can be attached to either a stack or an organization. Stack webhooks
will be notified whenever a stack is updated or changed. Organization
webhooks will be notified for events happening within each of the organization’s
stacks and organization-specific events like team or membership
changes.

There are some restrictions for the number of webhooks that can be registered
when using the Pulumi Team editions. Contact us
if you need the limit increased.

The Webhooks management page is on the Stack or Organization Settings tab.

Creating a Webhook

To create a new webhook, provide a display name, webhook
URL, and an optional shared secret.

If a shared secret is provided, webhook deliveries will contain a signature
in the HTTP request header that can be used to authenticate messages as coming from
the Pulumi Console.

For details on how to verify payload signatures, see the Headers section below.

Event Notifications

The following events will be emitted to webhooks registered to a stack or an organization.
Organization-level webhooks will be sent webhook events from all of the stacks within
that organization.

Event Kind

Triggered

stack_update

Whenever a stack is updated.

stack_preview

Whenever a stack update is previewed.

The following events are only delivered to organization-based webhooks.

Event Kind

Triggered

stack

Whenever a stack is created or deleted within an organization.

team

Whenever a team is created, updated, or deleted.

Payloads

Each webhook payload has a format specific to the payload being emitted. Every payload will contain a sender, organization,
and stack reference as appropriate. For examples of specific payloads, see Payload Reference below.

Each webhook will contain a user field, which is the user who requested the action, an organization which is
the organization name, and a URL for the event. It will also contain the stackName for the stack which was modified when applicable.

Headers

Payloads contain several headers.

Header

Description

Pulumi-Webhook-ID

Unique ID for each webhook sent which you can reference when looking at delivery logs in the Pulumi Console.

Pulumi-Webhook-Kind

The kind of webhook event, e.g. stack_update.

Pulumi-Webhook-Signature

Only set if the webhook has a shared secret. HMAC hex digest of the request payload, using the sha256 hash function and the webhook secret as the HMAC key.

The following snippets show how to compute and verify the webhook signature.
For examples in other languages, see danharper/hmac-examples.