Create a New Webhook Subscription

JFrog REST APIs

Products
JFrog Xray
Content Type
REST API
ft:sourceType
Paligo

Description: Registers a new Webhook subscription with a given input.

Security: Requires a valid admin user.

Usage: POST event/api/v1/subscriptions

Produces: application/json

Sample Input for Predefined Webhook:

{
  "key": "Audits",
  "description": "Triggers Security and QA audits when a new artifact is created",
  "enabled": true,
  "event_filter": {
    "domain": "artifact",
    "event_types": [
      "deployed",
      "moved",
      "copied"
    ],
    "criteria": {
        "anyLocal": true,
        "anyRemote": false,
        "includePatterns": [],
        "excludePatterns": [],
        "repoKeys": []
    }
  },
  "handlers": [
    {
      "handler_type": "webhook",
      "url": "https://webhook.my-company.test/",
      "secret": "tell no one",
      "proxy": "mainProxy",
      "custom_http_headers": [
        {
          "name": "X-MyCompany-Header",
          "value": "whatever"
        }
      ]
    }
  ]
}

Sample Output for Predefined Webhook:

{
  "key": "Audits",
  "description": "Triggers Security and QA audits when a new artifact is created",
  "enabled": true,
  "event_filter": {
    "domain": "artifact",
    "event_types": [
      "deployed",
      "moved",
      "copied"
    ],
    "criteria": {
        "anyLocal": true,
        "anyRemote": false,
        "includePatterns": [],
        "excludePatterns": [],
        "repoKeys": []
    }
  },
  "handlers": [
    {
      "handler_type": "webhook",
      "url": "https://webhook.my-company.test/",
      "secret": "tell no one",
      "proxy": "mainProxy",
      "custom_http_headers": [
        {
          "name": "X-MyCompany-Header",
          "value": "whatever"
        }
      ]
    }
  ]
}

When registering a Webhook subscription, the following elements are part of Artifactory itself; domain, event_types and criteria and have the following valid values:

domain

event-types

criteria

artifact
  • deployed

  • deleted

  • moved

  • copied

  • anyLocal

  • anyRemote

  • includePatterns

  • excludePatterns

  • repoKeys

artifact_property
  • added

  • deleted

docker
  • pushed

  • deleted

  • promoted

build
  • uploaded

  • deleted

  • promoted

  • anyBuild

  • selectedBuilds

  • includePatterns

  • excludePatterns

release_bundle
  • created

  • signed

  • deleted

  • anyReleaseBundle

  • includePatterns

  • excludePatterns

  • registeredReleaseBundlesNames

distribution
  • distribute_started

  • distribute_completed

  • distribute_aborted

  • distribute_failed

  • delete_started

  • delete_completed

  • delete_failed

  • anyReleaseBundle

  • includePatterns

  • excludePatterns

  • registeredReleaseBundlesNames

artifactory_release_bundle
  • received

  • delete_started

  • delete_completed

  • delete_failed

  • anyReleaseBundle

  • includePatterns

  • excludePatterns

  • registeredReleaseBundlesNames

Sample Request for Custom Webhook:

{
   "key": "trigger_action",
   "enabled": true,
   "event_filter": {
       "domain": "artifact",
       "event_types": [
           "deployed"
       ],
       "criteria": {
           "anyLocal": true
       }
   },
   "handlers": [
       {
           "handler_type": "custom-webhook",
           "url": "https://api.github.com/repos/your/repo/actions/workflows/artifact_deployed.yml/dispatches",
           "payload": "{ \"ref\": \"main\" , \"inputs\": { \"artifact_path\": \"{{.data.repo_key}}/{{.data.path}}\" } }",
                   "proxy": "mainProxy",
           "secrets": [
               {
                   "name": "token",
                   "value": "***"
               }
           ],
           "http_headers": [
               {
                   "name": "Authorization",
                   "value": "Bearer {{.secrets.token}}"
               },
               {
                   "name": "Accept",
                   "value": "application/vnd.github+json"
               },
               {
                   "name": "Content-Type",
                   "value": "application/json"
               }
           ]
       }
   ]
}

Parameter

Description

url

This is is the target URL that will get called.

Example: https://api.github.com/repos/your/repo/actions/workflows/artifact_deployed.yml/dispatches

http_headers

This is the list of HTTP headers (name+value) that will be added to the request.

payload

This is used to build the request body.

secrets

This is a set of sensitive values that will be injected in the request (headers and/or payload).

Note

It is possible to update the value of a secret (when a password changes, or a token expires). The Webhook will fail if the token expires. In such cases, you must update the token 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>

proxy

Indicates whether to send the Webhook through a proxy. You can select a proxy from the configured proxy servers list.

Sample Response for Custom Webhook:

{
    "enabled": true,
    "event_filter": {
        "criteria": {
            "anyLocal": true
        },
        "domain": "artifact",
        "event_types": [
            "deployed"
        ]
    },
    "handlers": [
        {
            "handler_type": "custom-webhook",
            "http_headers": [
                {
                    "name": "Authorization",
                    "value": "Bearer {{.secrets.token}}"
                },
                {
                    "name": "Accept",
                    "value": "application/vnd.github+json"
                },
                {
                    "name": "Content-Type",
                    "value": "application/json"
                }
            ],
            "payload": "{ \"ref\": \"main\" , \"inputs\": { \"artifact_path\": \"{{.data.repo_key}}/{{.data.path}}\" } }",
            "proxy": "mainProxy",
            "secrets": [
                {
                    "name": "token"
                }
            ],
            "url": "https://api.github.com/repos/your/repo/actions/workflows/artifact_deployed.yml/dispatches"
        }
    ],
    "key": "trigger_action"
}

Response Codes:

  • 201 Success of creation

  • 400 Bad Input

  • 409 Subscription conflicts with an existing one (e.g key)