Skip to main content

Webhooks

Last updated on

In the Artifact Registry in Harness, Triggers automate actions based on events related to your artifacts, and allow you to streamline workflows by responding dynamically to changes in your artifact repositories.

Before you begin​

  • Harness permissions: View and Edit on the artifact registry where you want to add a webhook. Go to RBAC in Harness to configure roles.
  • Trigger permissions: Create permission on triggers in the target pipeline if you plan to link the webhook to a CI or CD pipeline. Go to Platform triggers to understand trigger types.
  • Endpoint reachability: If you send events to an external system, the payload URL must be publicly reachable from Harness.

Package type support​

Webhooks are supported for all Artifact Registry package types other than Raw.

Types of triggers​

  1. Artifact Creation
    • Executes when a new artifact is pushed to the registry or cached through an upstream proxy.
    • Useful for automating deployments or notifying downstream systems.
  2. Artifact Deletion
    • Triggers when an artifact version is deleted or removed from the upstream proxy cache.
Upstream proxy registries

Webhook events fire for upstream proxy registries in addition to local registries. When a package is fetched from an external source and cached in your upstream proxy, an Artifact Creation event fires. Supported for Docker, Maven, npm, Python (PyPI), and NuGet upstream proxies.

Cosign signature and attestation filtering

Webhook triggers automatically filter out Cosign signature (.sig) and attestation (.att) OCI artifacts. Only the original image push triggers an event, preventing duplicate pipeline executions from auxiliary signing artifacts.

Add and use a webhook​

A webhook sends a notification to your app when a new artifact is pushed to the registry, and the trigger in your CD build pipeline automatically starts a deployment or build process in response to that notification. To configure and use a webhook, you need to:

  1. Create a webhook in the Artifact Registry.
  2. Create a trigger in the CD build pipeline.
  3. Configure the trigger to run against the webhook.

Test your webhook​

Test your webhook by pushing an artifact to the registry.

  1. Select your artifact registry.
  2. Select Set up client.
  3. Follow the on-screen instructions to test your webhook.

Once logged in to your registry type, the steps should look like this (using Docker as an example):

docker tag <IMAGE_NAME>:<TAG> pkg.app.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>:<TAG>
# e.g. docker tag my-image:latest pkg.app.harness.io/123456/my-registry/demoimg:v1

docker push pkg.app.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>:<TAG>
# e.g. docker push pkg.app.harness.io/123456/my-registry/demoimg:v1

Once you have pushed an artifact to the registry, you can review the trigger and executions in the Artifact Registry.

info

As this webhook was created by the trigger, while reviewing it, you cannot edit its configuration.

Use cases for triggers​

  • CI/CD Automation: Start a pipeline when a new artifact is ingested.
  • Version Control: Notify teams when a new version of an artifact is available.
  • Security & Compliance: Scan artifacts when they are pushed or updated.
  • Cleanup & Retention Policies: Automatically remove outdated artifacts.

Webhooks and artifact registry triggers​

Webhooks allow external systems to interact with Artifact Registry events in real time. Depending on your configuration, webhooks can either notify external systems about artifact-related events or enable external systems to trigger specific actions in Harness.

Example use case:

  • Outgoing webhooks: Notify a monitoring system when a new artifact is ingested or updated, enabling real-time tracking and validation.
  • Incoming webhooks: A third-party build system triggers an artifact ingestion event in Harness, automating downstream workflows.

Go to Platform triggers to review the types of triggers available, including webhook, artifact, manifest, and schedule triggers.

Troubleshooting​

I cannot add a webhook to my Raw registry

Webhooks are supported for all Artifact Registry package types other than Raw. If you need webhook-driven automation, use a supported package type for that workflow.

A Cosign signature (.sig) or attestation (.att) artifact push does not fire a webhook event

Webhook triggers automatically filter out Cosign signature (.sig) and attestation (.att) OCI artifacts by design. Only the original image push fires the event, which prevents duplicate pipeline executions from auxiliary signing artifacts. To fire an event on the underlying image, push the image itself.

The trigger fires but my pipeline does not execute

Verify that the trigger is Enforced and that the pipeline it targets has permission to run under the trigger's principal. Open the trigger execution history in the pipeline to see whether the trigger was invoked and, if so, why the run did not start.

Creating a webhook with a link-local or cloud metadata payload URL is rejected

Payload URLs pointing to link-local or cloud metadata endpoints (for example, http://169.254.169.254) are rejected at API level and cannot be saved. Older webhooks that were created before this validation was added may exist but fail at execution time under Harness runtime SSRF protection. Use a public or explicitly reachable endpoint instead.

The webhook shown for a trigger cannot be edited

Webhooks that are auto-created from a pipeline trigger are managed by the trigger itself and are read-only in the Artifact Registry UI. To change their configuration, edit the trigger in the pipeline that owns it. Webhooks created directly in the Artifact Registry UI remain fully editable.

Next steps​