Create a New Webhook Subscription

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

Security: Requires a valid admin user. Project admins can create Webhook subscriptions for the following domains: artifact, artifact_property, docker, and build. All other domains require a platform admin.

Usage: POST /event/api/v1/subscriptions

Produces: application/json

Sample Input for Predefined Webhook:

{
  "key": "Audits",
  "project_key": "catalina",
  "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` Note Refers to Release Bundle v1 used by JFrog Distribution.Create Release Bundles (v1)	`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`
`release_bundle_v2`	`release_bundle_v2_started` `release_bundle_v2_failed` `release_bundle_v2_completed`	`anyReleaseBundle` `selectedReleaseBundles`
`release_bundle_v2_promotion`	`release_bundle_v2_promotion_started` `release_bundle_v2_promotion_failed` `release_bundle_v2_promotion_completed`	`selectedEnvironments`

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",
           "method": "POST", //can be  any valid http verb
           "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"
            "method": "POST"
        }
    ],
    "key": "trigger_action"
}

Response Codes:

201 Success of creation
400 Bad Input
409 Subscription conflicts with an existing one (e.g key)

Note

Note