Skip to content


This example demonstrates how to use webhooks to perform actions during the lifecycle of package deployments. Webhooks are similar to Component Actions such that they both enable complex functionality to be executed during the lifecycle of a package deployment. The key difference between webhooks and actions is that actions are defined within the package’s zarf.yaml while webhooks are defined within the cluster that you are deploying your package onto.

This example uses Pepr as a mutating webhook that watches for any updates to a zarf package secret. As zarf deploys components, it updates a secret in the zarf namespace that ‘declares’ what components are being deployed. Pepr watches for these updates and runs an example operation for each component that gets deployed to the cluster. Since Pepr is a mutating webhook, as zarf updates the package secret for each component that is being deployed, Pepr will modify the secret to denote that a webhook operation is executing for that component. To account for this, every time zarf updates the package secret, it will check to see if a webhook has modified the secret and will wait if there are any webhooks in a Running state. The webhook itself is responsible for updating the secrets when it’s operations complete. zarf will poll the secret every second to check if the webhook is complete allowing it to continue deploying the rest of the package.

Webhooks have the potential to be extremely powerful. Since they are written in Javascript, they have the capability to do almost anything that you can do with JavaScript. This includes interacting with the Kubernetes API, interacting with other APIs, or even interacting with other systems. Caution should be exercised when deploying webhooks to clusters as they have the potential to run any time a new package is deployed to the cluster, and future package deployers might not be aware that the cluster has webhooks configured.

kind: ZarfPackageConfig
name: component-webhooks
description: Example Pepr Module for Component Webhooks
version: 0.0.1
- name: module
required: true
- name: module
namespace: pepr-system
- pepr-module-cb5693ef-d13c-5fe1-b5ad-c870fd911b3b.yaml