Webhooks

Webhooks are user-defined HTTP callbacks or event notification mechanisms that allow applications to send real-time information to other systems when specific events occur.

They enable seamless communication between systems by automatically triggering an HTTP request to a specified URL whenever the defined event takes place.

Webhooks are highly effective tools for automating workflows, integrating services, and providing updates without the need for constant polling.

Scopes and Events

Bluebricks provides hooks related to deployments within defined scopes. Webhook events are tied to deployments, such as deployment:created and deployment:updated, while scopes serve as contextual triggers.

At Bluebricks, there are three types of scopes: environments, blueprints, and deployments. Developers can register a webhook for each scope to receive notifications when a deployment is created or updated.

Examples

If a developer wants to be notified when a new deployment occurs in the production environment, the event would be deployment:created with the scope type set to environment and its value, production.

In this case, the developer will receive notifications for any new deployment taking place in production.

On the other hand, if the developer registers for both events; deployment:created and deployment:updated, they will receive notifications for any deployment event—creation or update—occurring in the production environment.

The events are agnostic to the deployment intention and include modifications, deletions, or even no-change actions.

Required Permission Scopes

Managing webhooks on Bluebricks requires users to have the following permission scopes:

• create:webhook

• update:webhook

• delete:webhook

How to Create a Webhook Subscription

Webhook subscriptions can be managed through the Bluebricks API or directly via the Bluebricks App. Follow the below steps to create your first webhook subscription:

1. Open the Account Settings Page and select the Webhooks tab

2. Click the Add Webhook button on the top right corner of the pane

3. Choose a name, set a URL, and choose Scope object and Events

4. Click the Create Webhook button at the bottom left corner of the sidebar

Scope Types

Environment

The environment scope type ensures that notifications are triggered for any deployments and updates within the selected environment, regardless of the blueprint. Use this scope type to track changes across the environment holistically.

Blueprint 🔜

The blueprint scope type triggers notifications based on deployments of a specific blueprint. Use this type if you want to be notified whenever a specific blueprint is deployed or modified.

Deployments

The deployment scope type ensures that notifications are triggered for any updates to a specific deployment. Use this scope type to track changes related to a particular deployment.

Events

deployment:created

The created event is triggered each time a new deployment activity occurs.

For example, this event will be triggered when a developer deploys a blueprint for the first time and each time they deploy an update to an existing one.

Bluebricks will call the webhook for each activity without tracking its progress or reporting its outcome (see red arrows below):

deployment:updated

The updated event is triggered for every change in the deployment lifecycle, excluding its creation. By subscribing to deployment:updated, developers will receive notifications for the following events:

Event	Key	Description
Planning	planning	Whenever Bluebricks begins predicting upcoming changes in the cloud and generates a deployment plan.
Waiting for Approval	planned	This is an optional event, dependent on the configuration set during the initiation of the deployment.
Plan Approved	plan_approved
Installing	installing	The active phase of the deployment, during which Bluebricks implements changes in the cloud environment.
Completed	completed	Triggered when the installation is successfully completed, and all changes have been implemented.
Canceled	canceled	Triggered when the deployment is canceled by an authorized user.
No Changes	no_change	Triggered, typically after the planning stage, when Bluebricks detects that no changes are required.

Payload Example

{
  "type": "deployment:updated",
  "webhook": {
    "id": "80df0bf0-4b05-4c96-9216-ec5057a71da2",
    "scope": "organization",
    "scope_id": "org_e5Oh1aexw4OUDZmd"
  },
  "blueprint": {
    "qualified_name": "@bluebricks/eks_core",
    "version": "1.12.0"
  },
  "deployment": {
    "id": "2a151a4b-874b-46d8-8f34-a803c80a69fe",
    "slug": "bluebricks-eks-api-core-us-west-1",
    "created_at": "2025-03-02T11:39:36.585Z",
    "initiated_by": {
      "name": "George Clinton",
      "email": "[email protected]"
    },
    "reviewed_by": null,
    "changes": {
      "stage": "planned",
      "archived": null
    },
    "plan_url": "https://app.bluebricks.co/plan/2a151a4b-874b-46d8-8f34-a803c80a69fe",
  },
  "environment": {
    "id": "4145de0d-bfc4-4df9-a067-c6f06d8f4fb0",
    "slug": "staging-us",
    "name": "Staging Env / US",
    "created_at": "2025-02-04T14:36:57.960Z"
  },
  "organization": {
    "id": "org_e5Oh1aexw4OUDZmd",
    "slug": "Bluebricks",
    "name": "bluebricks"
  }
}