Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Artifact RegistryAutomationIntegration

Create a webhook

Create a webhook on a registry to send artifact events to an external URL when an artifact is pushed or deleted, and test the delivery.

A webhook on a registry sends an HTTP POST request to a URL you specify each time an artifact event occurs. You configure which events trigger the webhook and optionally secure the payload with a secret.

Before you begin

  • Your role must include View and Edit permission on the registry. Go to RBAC and permissions for details.

  • The payload URL must be publicly reachable from Harness. Localhost, private network addresses, and cloud metadata endpoints are not accepted. Go to Webhooks overview for the full URL requirements.

  • Webhooks are supported for all registry formats except Raw.

Create a webhook

  1. In the left navigation, select Registries.

  2. Click the registry where you want to add the webhook.

  3. Select the Webhooks tab.

  4. Click Create webhook (or Add webhook, depending on your version).

  5. Fill in the webhook form:

    Field
    Description

    Name

    A short, descriptive label for the webhook. Used to identify it in the Webhooks list.

    Description

    Optional. Notes about the webhook's purpose.

    Payload URL

    The endpoint that will receive the event. Must start with http:// or https:// and be publicly reachable.

    Secret

    Optional. A shared secret used to sign the payload. Create a new secret or select an existing Harness secret. Use this to verify that events come from Harness.

    Triggers

    Select Send me everything to subscribe to all events, or select specific events: Artifact Creation and/or Artifact Deletion.

    SSL verification

    Enable to verify the SSL certificate of the payload URL. Disable only for testing with self-signed certificates; always enable for production endpoints.

    Custom headers

    Optional key-value pairs added to every outgoing request. Useful for passing authentication tokens required by your endpoint.

  6. Click Create webhook (or Save).

The webhook appears in the Webhooks tab. Harness sends a ping request to the payload URL to confirm reachability.

Test a webhook

Push an artifact to the registry to trigger an Artifact Creation event and verify the webhook fires.

  1. Go to the registry and select Setup Client from the row menu.

  2. Follow the authentication steps for your package format.

  3. Push an artifact using your client.

After the push, return to the Webhooks tab and check the delivery log for the webhook. A successful delivery shows an HTTP 2xx response from your endpoint.

If your endpoint is not yet live, use a service such as webhook.site to inspect the payload before pointing the webhook at your production URL.

Webhooks created by pipeline triggers

When you create a Harness CD trigger linked to an artifact event, Harness automatically creates a corresponding webhook in the registry. These auto-created webhooks are read-only in the Artifact Registry UI because they are owned by the pipeline trigger. To modify them, edit the trigger in the pipeline. You can identify them in the Webhooks list by the pipeline name in the description.

Troubleshooting

The payload URL is rejected when I save the webhook

Harness validates the URL at save time. Rejected addresses include: localhost and loopback addresses (127.0.0.1, ::1), private network ranges (RFC 1918: 10.x, 172.16–31.x, 192.168.x), link-local addresses (169.254.x.x), and cloud metadata endpoints. Use a public URL or a tunneling service during local development.

The webhook fires but my pipeline does not start

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

I do not receive events for Cosign signature or attestation pushes

This is expected behavior. Artifact Registry automatically filters out Cosign .sig and .att OCI artifacts to prevent duplicate pipeline executions. Only the original image push fires the event.

I created a webhook but it cannot be edited

Webhooks auto-created by pipeline triggers are read-only in the registry UI. Edit the trigger in the owning pipeline to change the configuration. Webhooks you create directly in the registry remain fully editable.

Next steps

Last updated

Was this helpful?