Webhooks

Overview

A Webhook is an automated notification mechanism that is triggered by events that you define. When a webhook is triggered, it sends relevant information about the event to a web location that is listening for that specific event notification. The webhook is comprised of three simple components – the triggering event, the information about the event (the “payload”), and the web location listening for the event.

As a JFrog Platform administrator, you will be able to use Webhooks to trigger an action in another service in response to an event in Artifactory, either to notify users of the event or trigger some automated flow.

Since Artifactory plays an important role in the build and distribution process of your artifacts, it is helpful to know when important events are occuring. Webhooks enables you to be notified or notify other users when such events take place in Artifactory.

Webhooks enables you to integrate Artifactory processes with third party applications that are also essential to your build process. Some Artifactory events may trigger a process in another application, such as Jira, and Jenkins. For example, when a certain event is triggered, such as build promotion, Artifactory will send an HTTP POST payload to the Webhook’s configured URL and trigger a CI build in Jenkins.

How does it work?

Webhooks is based on the JFrog Event Service. This microservice is responsible for the distribution of your Webhook events asynchronously. To learn more about it, see System Architecture.

Page Contents

Create Webhooks in the JFrog Platform

There are two types of Webhooks:

Predefined: These are Webhooks with predefined payloads, which cannot be customized for specific vendors. Users, however, can customize the target URL and add HTTP headers.

Custom: These are Webhooks whose HTTP request headers and payload can be fully customized to adapt to any target service, such as GitHub actions, Gitlab pipelines, Jenkins jobs, Slack, and more. Custom Webhooks trigger events with the format expected by the vendor.

Predefined Webhooks

To start creating Webhooks, do the following:

Navigate to Administration Module | General | Webhooks and click New Webhook.
JFrog Cloud New Interface (Beta)
On the taskbar, click(Platform Configurations), and select Platform Management > Webhooks. To learn more, click here.

Enter the details of the following fields:

Field	Description
Enabled	When unchecked the Webhook is ignored when events occur.
URL	Specifies the URL that the Webhook invokes. This will be the URL that Artifactory will send an HTTP POST request to.
Use Proxy	Indicates whether to send the Webhook through a proxy. You can select a proxy from the configured proxy servers list.
Event	Displays the list of Events in Artifactory, Xray, and Distribution that function as the event trigger for the Webhook.
Secret Token	Defines a secret authentication token. As an admin, you can determine the way in which the webhook's secret token should be used: Use the secret authentication token as the “X-JFrog-Event-Auth” HTTP header, so that the token can be used by the service that receives the event to authenticate the event emitter Used to sign the events payload - in which case the secret token it must not be passed as a header
Use secret for payload signing	If the checkbox "Use secret for payload signing" is selected, the secret will be used to sign the events payload and will be passed as the “X-JFrog-Event-Auth” HTTP header". Note that custom http headers cannot be trusted on the webhook target side - because since they are not signed, they can be tampered with by any man-in-the-middle.
Custom Headers	Adds custom headers you wish to use to invoke the Webhook.

By default, private networks are not allowed to be used as Webhook targets for security reasons. If you would like to allow use of a private network, change the URL strict policy configuration in the system.yaml file: urlStrictPolicy: true. See Artifactory System YAML.

Some events can be applied to repositories, builds and Release Bundles:
Events such as artifact was deployed, moved, added can be applied on every repository in Artifactory or on a list of specific repositories, based on a specific list or by using include/exclude patterns.
Note that if you select any local and/or remote repository, the Webhook will be applied on all existing repositories and any repositories you create in the future.

Events such as build was deployed, promoted, deleted can be applied on every new build that is uploaded to Artifactory or on a list of specific builds, based on a specific list or by using include/exclude patterns.

Release Bundle and Distribution events can be applied on every new Release Bundle or on a list of specific Release Bundles, based on a specific list or by using include/exclude patterns.

Custom Webhooks

To create a custom webhook:

Navigate to Administration Module | General | Webhooks and click New Webhook:
Click the Custom toggle.

Enter the details of the following fields:

Field	Description
Enabled	When unchecked the Webhook is ignored when events occur.
URL	Specifies the URL that the Webhook invokes. This will be the URL that Artifactory will send an HTTP POST request to. Example : `https://api.github.com/repos/myrepo/actions/workflows/artifact_deployed.yml/dispatches`
Event	Displays the list of Events in Artifactory, Xray, and Distribution that function as the event trigger for the Webhook.
Secrets	Defines a set of sensitive values (such as, tokens and passwords) that can be injected in the headers and/or payload. Secrets’ values are encrypted. In the header/payload, the value can be invoked using the `{{.secrets.token}}` format, where `token` is the name provided for the secret value. Click Add Secret to add more than one secret. It is possible to update the value of a secret (when a password changes, or a token expires) using the following REST API call: `PUT /event/api/v1/subscriptions/<sub-key>/secrets/<secret-name>` Authorization : Bearer <admin token> Content-Type : text/plain < secret-value>
Headers	Adds HTTP headers you wish to use to invoke the Webhook. Click Add Header to add more than one header.
Payload	The custom payload you want to send to the target service. In the payload, values can be invoked using dotted-syntax. Example { "ref": "main", "inputs": { "artifact_path": "{{.data.repo_key}}/{{.data.path}}" } } To know what values can be injected in the payload (as well as in HTTP headers), see the Event Types section below.

Optionally, you can click Test to send a fake HTTP request to the target URL and verify that the webhook is working fine.
Click Create.

Test a Webhook

You can test a Webhook using the Test button in the UI, to check the connectivity between Artifactory and the configured URL. The Webhook will be triggered manually, and a dummy payload will be sent to the configured URL.

Event Types

The following are the supported event types according to each domain with an example for each event of the payload that will be sent to the configured URL.

Domain: Artifact

Includes events that are triggered when certain artifact events occur in Artifactory:

Event: deployed

The Webhook is triggered when an artifact is deployed to a repository. You can select the repositories and repository paths on which the Webhook will be applied.

Artifact was Deployed

{
  "domain": "artifact",
  "event_type": "deployed",
  "data": {
    "repo_key": "example-repo-local",
    "path": "pipeinfo7.json",
    "name": "pipeinfo7.json",
    "sha256": "8b6cd18345075ff248487fed24e87ff0acff1454e761cc0676f78fc898dff7a7",
    "size": 203
  },
  "subscription_key": "jfdev-agent",
  "source": "jfrog/jfrt@01fsmwgxevmmcr1ajmvhfw1j9s"
}

Event: deleted

The Webhook is triggered when an artifact is deleted from a repository. You can select the repositories on which the Webhook will be applied.

Artifact was Deleted

{
  "repo_key":"sample_repo",
  "event_type":"deleted",
  "path":"sample_path_dir/sample_artifact",
  "name":"sample_artifact",
  "sha256":"ec1be623d148ed220f70f4f6125dc738b1d301a85b75e87c5b554fa3bb1b4141",
  "size":17848
}

Event: moved

The Webhook is triggered when an artifact is moved from a repository. You can select the repositories and repository paths on which the Webhook will be applied. The Webhook will apply on the repositories from which the artifact is moved.

Artifact was Moved

{
  "repo_key":"sample_repo",
  "event_type":"moved",
  "path":"sample_path_dir/sample_artifact",
  "name":"sample_artifact",
  "size":0,
  "source_repo_path":"sample_repo/sample_path_dir/sample_artifact",
  "target_repo_path":"target_repo/sample_path_dir/sample_artifact"
}

Event: copied

The Webhook is triggered when an artifact is copied from a repository. You can select the repositories and repository paths on which the Webhook will be applied. The Webhook will apply on the repositories from which the artifact is copied.

Artifact was Copied

{
  "repo_key":"sample_repo",
  "event_type":"copied",
  "path":"sample_path_dir/sample_artifact",
  "name":"sample_artifact",
  "size":0,
  "source_repo_path":"sample_repo/sample_path_dir/sample_artifact",
  "target_repo_path":"target_repo/sample_path_dir/sample_artifact"
}

Event: cached

The Webhook is triggered for each artifact that is pulled from a new remote repository. Webhooks are generated when downloading remote artifacts, for example: npm install busybox. If a webhook can be generated for push replication and the downloading of a remote artifact then it should also work for pull replication as well.

Artifact was Cached

{
  "repo_key":"sample_repo",
  "event_type":"cached", 
  "path":"sample_path_dir/sample_artifact",
  "name":"sample_artifact",
  "sha256":"ec1be623d148ed220f70f4f6125dc738b1d301a85b75e87c5b554fa3bb1b4141",
  "size":17848
}

Domain: Artifact Properties

Includes events that are triggered when certain artifact property actions occur in Artifactory:

Event: added

The Webhook is triggered when a property is added to an artifact/folder in a repository, or the repository itself. You can select the repositories and repository paths on which the Webhook will be applied.

Artifact Property was Added

{
   "repo_key":"sample_repo",
   "event_type":"added", 
   "path":"sample_path_dir/sample_artifact",
   "name":"sample_artifact",
   "sha256":"ec1be623d148ed220f70f4f6125dc738b1d301a85b75e87c5b554fa3bb1b4141",
   "size":17848,
   "property_key":"sample_prop_key",
   "property_values":[
   "sample_value"
 ]
}

Event: deleted

The Webhook is triggered when a property is deleted from an artifact/folder in a repository, or the repository itself. You can select the repositories and repository paths on which the Webhook will be applied.

Artifact Property was Deleted

{
   "repo_key":"sample_repo",
   "event_type":"deleted", 
   "path":"sample_path_dir/sample_artifact",
   "name":"sample_artifact",
   "sha256":"ec1be623d148ed220f70f4f6125dc738b1d301a85b75e87c5b554fa3bb1b4141",
   "size":17848,
   "property_key":"sample_prop_key",
   "property_values":[
   "sample_value"
 ]
}

Domain: Docker

Includes events that are triggered when certain Docker-related events occur in Artifactory:

Event: pushed

The Webhook is triggered when a new tag of a Docker image is pushed to a Docker repository. You can select the Docker repositories and repository paths on which the Webhook will be applied.

Docker Tag was Pushed

{
   "repo_key":"docker-remote-cache",
   "event_type":"pushed",
   "path":"library/ubuntu/latest/list.manifest.json",
   "name":"list.manifest.json",
   "sha256":"35c4a2c15539c6c1e4e5fa4e554dac323ad0107d8eb5c582d6ff386b383b7dce",
   "size":1206,
   "image_name":"library/ubuntu",
   "tag":"latest",
   "platforms":[
      {
         "architecture":"amd64",
         "os":"linux"
      },
      {
         "architecture":"arm",
         "os":"linux"
      },
      {
         "architecture":"arm64",
         "os":"linux"
      },
      {
         "architecture":"ppc64le",
         "os":"linux"
      },
      {
         "architecture":"s390x",
         "os":"linux"
    }
  ]
}

Event: deleted

The Webhook is triggered when a tag of a Docker image is deleted from a Docker repository. You can select the Docker repositories and repository paths on which the Webhook will be applied.

Docker Tag was Deleted

{
  "repo_key": "sample_repo",
  "event_type": "deleted",
  "path": "path/sample.txt",
  "name": "sample.txt",
  "sha256": "sample_checksum",
  "size": 0,
  "image_name": "sample_arch",
  "tag": "sample_image",
  "platforms": [
    {
      "architecture": "sample_os",
      "os": "sample_tag"
    }
  ]
}

Event: promoted

The Webhook is triggered when a tag of a Docker image is promoted. You can select the Docker repositories and repository paths on which the Webhook will be applied. The Webhook will apply on the Docker repositories from which the Docker tag was promoted.

Docker Tag was Promoted

{
  "repo_key": "sample_repo",
  "event_type": "promoted",
  "path": "path/sample.txt",
  "name": "sample.txt",
  "sha256": "sample_checksum",
  "size": 0,
  "image_name": "sample_arch",
  "tag": "sample_image",
  "platforms": [
    {
      "architecture": "sample_os",
      "os": "sample_tag"
    }
  ]
}

Domain: Build

Includes events that are triggered when certain build-related events occur in Artifactory:

Event: uploaded

The Webhook is triggered when a new build is uploaded. You can select the build names or build patterns on which the Webhook will be applied.

Build was Uploaded

{
  "build_name":"sample_build_name",
  "event_type":"uploaded",
  "build_number":"1",
  "build_started": "2020-06-18T14:40:49.869+0300"
}

Event: deleted

The Webhook is triggered when a build is deleted. You can select the build names or build patterns on which the Webhook will be applied.

Build was Deleted

{
  "build_name":"sample_build_name",
  "event_type":"deleted",
  "build_number":"1",
  "build_started":"2020-06-18T14:40:49.869+0300"
}

Event: promoted

The Webhook is triggered when a build is promoted. You can select the build names or build patterns on which the Webhook will be applied.

Build was Promoted

{
  "build_name":"sample_build_name",
  "event_type":"promoted",
  "build_number":"1",
  "build_started":"2020-06-18T14:40:49.869+0300"
}

Domain: Release Bundle

Includes events that are triggered when certain Release Bundle events occur in Artifactory:

Event: created

The Webhook is triggered when a Release Bundle is created. You can select the Release Bundle names or patterns on which the Webhook will be applied.

Release Bundle was Created

{
  "destination": "release_bundle",
  "event_type": "created",
  "data": {
    "release_bundle_name": "sample_name",
    "release_bundle_size": 9800,
    "release_bundle_version": "1.0.0"
  },
  "jpd_origin": "https://dist-pipe2.jfrogdev.co/artifactory"
}

Event: signed

The Webhook is triggered when a Release Bundle is signed. You can select the Release Bundle names or patterns on which the Webhook will be applied.

Release Bundle was Signed

{
  "destination": "release_bundle",
  "event_type": "signed",
  "data": {
    "release_bundle_name": "sample_name",
    "release_bundle_size": 9800,
    "release_bundle_version": "1.0.0"
  },
  "jpd_origin": "https://dist-pipe2.jfrogdev.co/artifactory"
}

Event: deleted

The Webhook is triggered when a Release Bundle is deleted. You can select the Release Bundle names or patterns on which the Webhook will be applied.

Release Bundle was Deleted

{
  "destination": "release_bundle",
  "event_type": "deleted",
  "data": {
    "release_bundle_name": "sample_name",
    "release_bundle_size": 9800,
    "release_bundle_version": "1.0.0"
  },
  "jpd_origin": "https://dist-pipe2.jfrogdev.co/artifactory"
}

Domain: Distribution

Includes events that are triggered when a Release Bundle version is distributed to one or more Edge nodes.

Event: distribute_started

The Webhook is triggered when Release Bundle distribution has started.

Distribution was Started

{
  "destination": "distribution",
  "event_type": "distribute_started",
  "data": {
    "edge_node_info_list": [
      {
        "edge_node_address": "https://artifactory-edge2-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge2"
      },
      {
        "edge_node_address": "https://artifactory-edge1-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge1"
      }
    ],
    "release_bundle_name": "test",
    "release_bundle_size": 1037976,
    "release_bundle_version": "1.0.0",
    "status_message": "CREATED",
    "transaction_id": 395969746957422600
  },
  "jpd_origin": "https://ga-dev.jfrogdev.co/artifactory"
}

Event: distribute_completed

The Webhook is triggered when Release Bundle distribution has completed.

Distribution was Completed

{
  "destination": "distribution",
  "event_type": "distribute_completed",
  "data": {
    "edge_node_info_list": [
      {
        "edge_node_address": "https://artifactory-edge2-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge2"
      },
      {
        "edge_node_address": "https://artifactory-edge1-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge1"
      }
    ],
    "release_bundle_name": "test",
    "release_bundle_size": 1037976,
    "release_bundle_version": "1.0.0",
    "status_message": "CREATED",
    "transaction_id": 395969746957422600
  },
  "jpd_origin": "https://ga-dev.jfrogdev.co/artifactory"
}

Event: distribute_aborted

The Webhook is triggered when Release Bundle distribution has been aborted.

Distribution was Aborted

{
  "destination": "distribution",
  "event_type": "distribute_aborted",
  "data": {
    "edge_node_info_list": [
      {
        "edge_node_address": "https://artifactory-edge2-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge2"
      },
      {
        "edge_node_address": "https://artifactory-edge1-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge1"
      }
    ],
    "release_bundle_name": "test",
    "release_bundle_size": 1037976,
    "release_bundle_version": "1.0.0",
    "status_message": "CREATED",
    "transaction_id": 395969746957422600
  },
  "jpd_origin": "https://ga-dev.jfrogdev.co/artifactory"
}

Event: distribute_failed

The Webhook is triggered when Release Bundle distribution has failed.

Distribution has Failed

{
  "destination": "distribution",
  "event_type": "distribute_failed",
  "data": {
    "edge_node_info_list": [
      {
        "edge_node_address": "https://artifactory-edge2-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge2"
      },
      {
        "edge_node_address": "https://artifactory-edge1-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge1"
      }
    ],
    "release_bundle_name": "test",
    "release_bundle_size": 1037976,
    "release_bundle_version": "1.0.0",
    "status_message": "CREATED",
    "transaction_id": 395969746957422600
  },
  "jpd_origin": "https://ga-dev.jfrogdev.co/artifactory"
}

Event: deletion_started

The Webhook is triggered when a Release Bundle version deletion has started on one or more Edge nodes.

Deleting a Release Bundle was Started

{
  "destination": "distribution",
  "event_type": "deletion_started",
  "data": {
    "edge_node_info_list": [
      {
        "edge_node_address": "https://artifactory-edge2-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge2"
      },
      {
        "edge_node_address": "https://artifactory-edge1-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge1"
      }
    ],
    "release_bundle_name": "test",
    "release_bundle_size": 1037976,
    "release_bundle_version": "1.0.0",
    "status_message": "CREATED",
    "transaction_id": 395969746957422600
  },
  "jpd_origin": "https://ga-dev.jfrogdev.co/artifactory"
}

Event: deletion_completed

The Webhook is triggered when a Release Bundle version deletion has completed from one or more Edge nodes.

Deleting a Release Bundle was Completed

{
  "destination": "distribution",
  "event_type": "deletion_completed",
  "data": {
    "edge_node_info_list": [
      {
        "edge_node_address": "https://artifactory-edge2-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge2"
      },
      {
        "edge_node_address": "https://artifactory-edge1-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge1"
      }
    ],
    "release_bundle_name": "test",
    "release_bundle_size": 1037976,
    "release_bundle_version": "1.0.0",
    "status_message": "CREATED",
    "transaction_id": 395969746957422600
  },
  "jpd_origin": "https://ga-dev.jfrogdev.co/artifactory"
}

Event: deletion_failed

The Webhook is triggered when a Release Bundle version deletion has failed on one or more Edge nodes.

Deleting a Release Bundle has Failed

{
  "destination": "distribution",
  "event_type": "deletion_failed",
  "data": {
    "edge_node_info_list": [
      {
        "edge_node_address": "https://artifactory-edge2-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge2"
      },
      {
        "edge_node_address": "https://artifactory-edge1-dev.jfrogdev.co/artifactory",
        "edge_node_name": "artifactory-edge1"
      }
    ],
    "release_bundle_name": "test",
    "release_bundle_size": 1037976,
    "release_bundle_version": "1.0.0",
    "status_message": "CREATED",
    "transaction_id": 395969746957422600
  },
  "jpd_origin": "https://ga-dev.jfrogdev.co/artifactory"
}

Domain: Destination

Includes events that are triggered when a Release Bundle status changes on Edge Nodes.

Requires Artifactory version 7.15.1 and above.

Event: received

The Webhook is triggered when a Release Bundle was received on an Edge Node.

Release Bundle was Received

{
  "destination": "artifactory_release_bundle",
  "event_type": "received",
  "data": {
    "release_bundle_name": "test",
    "release_bundle_version": "1.0.0",
    "status_message": "COMPLETED
  },
  "jpd_origin": "https://dist-pipe2.jfrogdev.co/artifactory"
}

Event: delete_started

The Webhook is triggered when a Release Bundle deletion from an Edge Node completed.

Release Bundle Deletion Started

{
  "destination": "artifactory_release_bundle",
  "event_type": "delete_started",
  "data": {
    "release_bundle_name": "test",
    "release_bundle_version": "1.0.0",
    "status_message": "COMPLETED
  },
  "jpd_origin": "https://dist-pipe2.jfrogdev.co/artifactory"
}

Event: delete_completed

The Webhook is triggered when a Release Bundle deletion from an Edge Node completed.

Release Bundle Deletion Completed

{
  "destination": "artifactory_release_bundle",
  "event_type": "delete_completed",
  "data": {
    "release_bundle_name": "test",
    "release_bundle_version": "1.0.0",
    "status_message": "COMPLETED
  },
  "jpd_origin": "https://dist-pipe2.jfrogdev.co/artifactory"
}

Event: delete_failed

The Webhook is triggered when a Release Bundle deletion from an Edge Node fails.

Release Bundle Deletion Failed

{
  "destination": "artifactory_release_bundle",
  "event_type": "delete_failed",
  "data": {
    "release_bundle_name": "test",
    "release_bundle_version": "1.0.0",
    "status_message": "COMPLETED
  },
  "jpd_origin": "https://dist-pipe2.jfrogdev.co/artifactory"
}

Webhooks REST API Support

To use REST API for creating, updating, and deleting Webhooks, see Webhooks.

Content

Space Tools

JFrog Help Center

Webhooks

Overview

How does it work?

Create Webhooks in the JFrog Platform

Predefined Webhooks

Enabled

URL

Use Proxy

Event

Secret Token

Use secret for payload signing

Custom Headers

Custom Webhooks

Enabled

URL

Event

Secrets

Headers

Payload

Test a Webhook

Event Types

Domain: Artifact

Event: deployed

Event: deleted

Event: moved

Event: copied

Event: cached

Domain: Artifact Properties

Event: added

Event: deleted

Domain: Docker

Event: pushed

Event: deleted

Event: promoted

Domain: Build

Event: uploaded

Event: deleted

Event: promoted

Domain: Release Bundle

Event: created

Event: signed

Event: deleted

Domain: Distribution

Event: distribute_started

Event: distribute_completed

Event: distribute_aborted

Event: distribute_failed

Event: deletion_started

Event: deletion_completed

Event: deletion_failed

Domain: Destination

Event: delete_started

Event: delete_completed

Event: delete_failed

Webhooks REST API Support