Custom Webhooks

To create a custom webhook:

1. Select All Projects, or from the Projects list, select the specific project for which to create a webhook.

2. Select the Platform module, then select Integrations > Webhooks.

3. Click New Webhook.

   

4. Click the Custom toggle.

   

5. Enter the name and description of the webhook.

6. Enter the URL that the webhook invokes.

   For example: https://api.github.com/repos/myrepo/actions/workflows/artifact_deployed.yml/dispatches

7. Select the HTTP method that the webhook should use.

   You can choose from POST, PUT, GET, PATCH, and DELETE. The default selection is POST.

8. Select a proxy server from the list of configured proxy servers in the Use Proxy dropdown if you want to send the webhook through a proxy.

   Applicable only for a self-hosted JFrog Platform installation

9. Select whether to show the results of the successful execution of the webhooks in the Troubleshooting tab.

10. Select the event or events that should trigger the webhook from the drop-down list: hover over the resource type to see the available events, and select the checkbox for events you want to include.

    
    

    📘

    Note

    For a webhook associated with a specific project, event types are limited to those for Artifacts, Docker, Artifact Properties, and Builds.

11. Select resources that the webhook will work on in the dialog window, and click Save. For example:

    • For Artifacts, you can apply events such as Artifact was deployed, moved, and added to artifacts in any repository or in a list of repositories, by selecting manually or by using an include/exclude pattern.

      
      

      📘

      Note

      If you select any local and/or remote repository, the webhook is applied on all existing repositories and any repositories you create in the future.

      

    • For builds, you can apply events such as build was deployed, promoted, and deleted to every new build that is uploaded to Artifactory or to a list of builds, by selecting manually or by using an include/exclude pattern.

      

    • For AppTrust, you can apply entry/ exit gate, release, version, and application events to specific applications or stages.

      

11. (Optional) Add secrets to the webhook: these define a set of sensitive values (such as tokens and passwords) that can be injected into the headers and/or payload. The values of the secrets are encrypted.

    Invoke the value In the header/payload using the {{.secrets.token}} format, where token is the name provided for the secret value.

    Click Add Secret to add more than one secret.

12. Add HTTP headers you wish to use to invoke the webhook.

    Click Add Header to add more than one header.

13. Enter the custom payload that you want to send to the target service.

    In the payload, you can invoke values using dotted syntax. For more information, see Custom Webhooks Payload Templates.

    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 Event Types.

14. Click Test to test the configuration.

    Sends a fake HTTP request to the target URL and verifies that the webhook is working fine.

15. Click Create to save the webhook configuration.

Custom Webhooks Payload Templates

JFrog Custom Webhooks use a similar payload-templating approach to Golang text templates , but are limited to only two actions. In payloads, you can:

• Display dynamic scalar values by rendering a textual representation for the variables: For example, {{ variable_name }}.
• Use json or yaml functions on an object to convert them into JSON or YAML format, to prepare the object for transmission or storage. For example, {{ json object_name }}.

Three root objects are supported: data, secrets, and userContext.

Example

To create a custom webhook to automate Kubernetes deployments as part of this workflow, you can use this payload template:

{
    "event_type" : "hot-deploy",
    "client_payload" :  {
        "tag" : "{{ .data.tag }}"
    }
}

Custom Webhooks Examples

The following are some examples of custom webhooks for various services.

GitHub Example

    {
        "key": "subscriptionOnGithub",
        "description": "some custom webhook subscription",
        "enabled": true,
        "event_filter": {
            "criteria": {
                "anyLocal": true
            },
            "domain": "artifact",
            "event_types": [
                "deployed"
            ]
        },
        "handlers": [
            {
                "handler_type": "custom-webhook",
                "url": "https://api.github.com//<username>/<reponame>/dispatches",
                "payload": "{\"event_type\": \"someEventType\"}",
                "secrets": [
                    {
                        "name": "token",
                        "value": "XXX"
                    }
                ],
                "http_headers": [
                    {
                        "name": "Authorization",
                        "value": "Bearer {{ .secrets.token }}"
                    }
                ]
            }
        ]
    }

GitLab Example

{
    "key": "subscriptionOnGitlab",
    "description": "some custom webhook subscription",
    "enabled": true,
    "event_filter": {
        "domain": "artifact",
        "event_types": [
            "deployed"
        ],
        "criteria": {
            "anyLocal": true,
            "anyRemote": false,
            "includePatterns": [],
            "excludePatterns": [],
            "repoKeys": []
        }
    },
    "handlers": [
        {
            "handler_type": "custom-webhook",
            "url": "http://<gitlaburl>/api/v4/projects/2/ref/main/trigger/pipeline",
            "secrets": [
                {
                    "name": "privatetoken",
                    "value": "XXXXX"
                },
                {
                    "name": "accesstoken",
                    "value": "XXXXXX"
                },
                {
                    "name": "token",
                    "value": "XXXXXXX"
                }
            ],
            "http_headers": [
                {
                    "name": "PRIVATE-TOKEN",
                    "value": "{{ .secrets.privatetoken  }}"
                },
                {
                    "name": "Content-Type",
                    "value": "application/x-www-form-urlencoded"
                }
            ],
            "payload": "token={{ .secrets.token }}&variables[TEST_VAR_CHECKSUM]={{ .data.sha256 }}&variables[ACCESS_TOKEN]={{ .secrets.accesstoken }}"
        }
    ]
}

Jenkins Example

{
    "key": "subscriptionOnJenkins",
    "description": "some custom webhook subscription",
    "enabled": true,
    "event_filter": {
        "criteria": {
            "anyLocal": true
        },
        "domain": "artifact",
        "event_types": [
            "deployed"
        ]
    },
    "handlers": [
        {
            "handler_type": "custom-webhook",
            "url": "http://<jenkinsurl>/job/test/buildWithParameters",
            "secrets": [
                {
                    "name": "token",
                    "value": "mytoken"
                },
                {
                    "name": "restapitoken",
                    "value": "XXXXX"
                }
            ],
            "http_headers": [
                {
                    "name": "Content-Type",
                    "value": "application/x-www-form-urlencoded"
                },
                {
                    "name": "Authorization",
                    "value": "Basic {{ .secrets.restapitoken }}"
                }
            ],
            "payload": "token={{ .secrets.token }}&sha256={{ .data.sha256 }}"
        }
    ]
}

Slack Integration Example

{
  "key": "customwebhook",
  "description": "notify slack channel at artifact deploy",
  "enabled": true,
  "event_filter": {
    "domain": "artifact",
    "event_types": [
      "deployed"
    ],
    "criteria": {
      "anyLocal": true,
      "anyRemote": false,
      "excludePatterns": [],
      "includePatterns": [],
      "repoKeys": []
    }
  },
  "handlers": [
    {
      "handler_type": "custom-webhook",
      "url": "https://hooks.slack.com/services/XXXX",
      "payload": "{\"text\": \"Hello from custom webhook triggered by event type {{ .type }}\"}",
      "http_headers": [
        {
          "name": "Content-type",
          "value": "application/json"
        }
      ]
    }
  ]
}