Webhooks

Run Codefresh pipelines or Kubernetes Jobs after an Environment deploys, fails, or is torn down.

Lifecycle can invoke third-party services when an Environment status changes.

Webhooks can run tests, clean up resources, or send notifications for specified Environment statuses.

Supported types

Lifecycle supports three types of webhooks:

codefresh: Trigger Codefresh pipelines.
docker: Run Docker images as Kubernetes Jobs.
command: Run shell commands in a specified Docker image.

Example operations

When an Environment status is deployed, trigger end-to-end tests.
When an Environment status is error, clean up infrastructure or send an alert to the team.
Run security scans on built containers.
After deployment, run database migrations.
Send notifications to communication channels.
Run smoke tests in custom test containers.

Configuration

Define webhooks in the environment.webhooks section of lifecycle.yaml.

This example triggers end-to-end tests when the Environment reaches deployed.

An administrator can disable all lifecycle.yaml webhooks. If no configured webhook starts, ask the administrator whether webhooks are available.

Examples

`codefresh`

The codefresh type triggers existing Codefresh pipelines when an Environment status changes.

state: deployed: Triggers the webhook when the Environment reaches deployed.
type: codefresh: Specifies a Codefresh pipeline webhook.
name: A human-readable name for the webhook.
pipelineId: The unique Codefresh pipeline ID.
trigger: The Codefresh pipeline trigger to run. This value is necessary.
env: Passes specified environment variables, such as branch and TEST_URL.

state: error: Triggers the webhook when the Environment fails.
type: codefresh: Invokes a Codefresh cleanup pipeline.
trigger: cleanup: Runs the Codefresh pipeline’s cleanup trigger.
env: Includes necessary variables, such as branch and CLEANUP_TARGET.

`docker`

The docker type runs a Docker image as a Kubernetes Job when an Environment status changes.

Docker webhooks run as Kubernetes Jobs in the same namespace as the Environment. They have a default timeout of 30 minutes and resource limits of 200m CPU and 1Gi memory.

docker.image: Docker image to run. You must supply this field.
docker.command: Optional override for the default entry point.
docker.args: Optional arguments for the command.
docker.timeout: Optional maximum run time in seconds. The default is 1800, and the permitted range is 1–86400.

`command`

The command type runs shell scripts and simple commands in a Docker image.

⚠️

Do not commit credentials or secret-bearing webhook URLs in lifecycle.yaml. Webhook env does not resolve cloud secret references. If a receiver needs authentication, use an approved credential-delivery mechanism. The target Job or pipeline must accept the mechanism.

command.image: Docker image for the script. You must supply this field.
command.script: Shell script to run. You must supply this field.
command.timeout: Optional maximum run time in seconds. The default is 1800, and the permitted range is 1–86400.

Trigger states

Webhooks can run for these Environment statuses:

deployed: The Services deployed correctly.
error: A build or deployment failed.
torn_down: Lifecycle tore down the Environment.

Use only these lowercase values. A different value does not start a webhook.

⚠️

Webhook env resolves Lifecycle template variables, but it does not resolve cloud secret references such as {{aws:path:key}}. The webhook receives that reference as literal text. Use a secret delivery mechanism supported by the target Job or pipeline.

Behavior

Lifecycle starts matching webhooks for the same status serially in configured order.
Webhook failures do not change the build status.
The Environment’s Webhooks page shows the invocation history that the v2 API returns.
Docker and command webhook logs are available after the Job completes. Lifecycle does not stream them while the Job runs.

Build metadata links Service Dependencies