Webhooks

Lifecycle can invoke third-party services when a build state changes.

Webhooks allow users to automate external processes such as running tests, performing cleanup tasks, or sending notifications based on environment build states.

Supported Types

Lifecycle supports three types of webhooks:

1. codefresh - Trigger Codefresh pipelines
2. docker - Execute Docker images as Kubernetes jobs
3. command - Run shell commands in a specified Docker image

Common Use Cases

• When a build status is deployed, trigger end-to-end tests.
• When a build status is error, trigger infrastructure cleanup or alert the team.
• Run security scans on built containers.
• Execute database migrations after deployment.
• Send notifications to Slack, Discord, or other communication channels.
• Perform smoke tests using custom test containers.

Configuration

Webhooks are defined in the lifecycle.yaml under the environment.webhooks section.

Below is an example configuration for triggering end-to-end tests when the deployed state is reached.

Examples

codefresh

The codefresh type triggers existing Codefresh pipelines when build states change.

• state: deployed → Triggers the webhook when the build reaches the deployed state.
• type: codefresh → Specifies that this webhook triggers a Codefresh pipeline.
• name → A human-readable name for the webhook.
• pipelineId → The unique Codefresh pipeline ID.
• trigger → Codefresh pipeline’s trigger to execute.
• env → Passes relevant environment variables (e.g., branch and TEST_URL).

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

docker

The docker type allows you to execute any Docker image as a Kubernetes job when build states change.

• docker.image → Docker image to execute (required)
• docker.command → Override the default entrypoint (optional)
• docker.args → Arguments to pass to the command (optional)
• docker.timeout → Maximum execution time in seconds (optional, default: 1800)

command

The command type is a simplified version of Docker webhooks, ideal for running shell scripts or simple commands.

• command.image → Docker image to run the script in (required)
• command.script → Shell script to execute (required)
• command.timeout → Maximum execution time in seconds (optional, default: 1800)

Trigger states

Webhooks can be triggered on the following build states:

• deployed → Service successfully deployed and running
• error → Build or deployment failed
• torn_down → Environment has been destroyed

Note

• All webhooks for the same state are executed serially in the order defined.
• Webhook failures do not affect the build status.
• Webhook invocations can be viewed at /builds/[uuid]/webhooks page(latest 20 invocations). Use the API to view all invocations.
• docker and command type’s logs are not streamed when the job is still in progress and are available only after the job completes.