[JENKINS-74913] Allow extension point in bitbucket source plugin to provide a implementation for web-hooks management

Add webhook extensible interface to provide custom implementation of wehbook from configuration to the APIs to register it on Bitbucket

Author: nfalco79

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhook.java

@@ -0,0 +1,51 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025, Falco Nikolas
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.cloudbees.jenkins.plugins.bitbucket.api.webhook;
+
+import edu.umd.cs.findbugs.annotations.CheckForNull;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import hudson.model.Describable;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.Beta;
+
+@Restricted(Beta.class)
+public interface BitbucketWebhook extends Describable<BitbucketWebhook> {
+
+    /**
+     * Name to use to describe the hook implementation.
+     *
+     * @return the name to use for the implementation
+     */
+    @CheckForNull
+    String getDisplayName();
+
+    /**
+     * The hook implementation identifier.
+     *
+     * @return the unique identifier for this implementation
+     */
+    @NonNull
+    String getId();
+
+}

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhookDescriptor.java

@@ -0,0 +1,34 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2017, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.cloudbees.jenkins.plugins.bitbucket.api.webhook;
+
+import hudson.model.Descriptor;
+
+/**
+ * {@link Descriptor} for {@link BitbucketWebhook}s.
+ *
+ * @since 936.4.0
+ */
+public class BitbucketWebhookDescriptor extends Descriptor<BitbucketWebhook> {
+}

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/hook/BitbucketHookProcessor.java renamed to src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhookProcessor.java

@@ -21,7 +21,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.cloudbees.jenkins.plugins.bitbucket.api.hook;
+package com.cloudbees.jenkins.plugins.bitbucket.api.webhook;
 
 import com.cloudbees.jenkins.plugins.bitbucket.BitbucketSCMSource;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpoint;
@@ -47,7 +47,7 @@
  * the incoming request as much as possible or the hook will be rejected.
  */
 @Restricted(Beta.class)
-public interface BitbucketHookProcessor extends ExtensionPoint {
+public interface BitbucketWebhookProcessor extends ExtensionPoint {
     static final String SCAN_ON_EMPTY_CHANGES_PROPERTY_NAME = "bitbucket.hooks.processor.scanOnEmptyChanges";
 
     /**
@@ -104,11 +104,11 @@ default Map<String, Object> buildHookContext(@NonNull HttpServletRequest request
      * @param payload request
      * @param endpoint configured for the given
      *        {@link #getServerURL(Map, MultiValuedMap)}
-     * @throws BitbucketHookProcessorException when signature verification fails
+     * @throws BitbucketWebhookProcessorException when signature verification fails
      */
     void verifyPayload(@NonNull Map<String, String> headers,
                        @NonNull String payload,
-                       @NonNull BitbucketEndpoint endpoint) throws BitbucketHookProcessorException;
+                       @NonNull BitbucketEndpoint endpoint) throws BitbucketWebhookProcessorException;
 
     /**
      * Settings that will trigger a re-index of the multibranch

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/hook/BitbucketHookProcessorException.java renamed to src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhookProcessorException.java

@@ -21,15 +21,15 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.cloudbees.jenkins.plugins.bitbucket.api.hook;
+package com.cloudbees.jenkins.plugins.bitbucket.api.webhook;
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketException;
 
-public class BitbucketHookProcessorException extends BitbucketException {
+public class BitbucketWebhookProcessorException extends BitbucketException {
     private static final long serialVersionUID = 6682700868741672883L;
     private final int httpCode;
 
-    public BitbucketHookProcessorException(int httpCode, String message) {
+    public BitbucketWebhookProcessorException(int httpCode, String message) {
         super(message);
         this.httpCode = httpCode;
     }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/hooks/BitbucketSCMSourcePushHookReceiver.java

@@ -25,8 +25,8 @@
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpointProvider;
-import com.cloudbees.jenkins.plugins.bitbucket.api.hook.BitbucketHookProcessor;
-import com.cloudbees.jenkins.plugins.bitbucket.api.hook.BitbucketHookProcessorException;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookProcessor;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookProcessorException;
 import hudson.Extension;
 import hudson.ExtensionList;
 import hudson.model.UnprotectedRootAction;
@@ -93,7 +93,7 @@ public HttpResponse doNotify(StaplerRequest2 req) throws IOException {
         try {
             Map<String, String> reqHeaders = getHeaders(req);
             MultiValuedMap<String, String> reqParameters = getParameters(req);
-            BitbucketHookProcessor hookProcessor = getHookProcessor(reqHeaders, reqParameters);
+            BitbucketWebhookProcessor hookProcessor = getHookProcessor(reqHeaders, reqParameters);
 
             String body = IOUtils.toString(req.getInputStream(), StandardCharsets.UTF_8);
             if (StringUtils.isEmpty(body)) {
@@ -120,37 +120,37 @@ public HttpResponse doNotify(StaplerRequest2 req) throws IOException {
             String eventType = hookProcessor.getEventType(Collections.unmodifiableMap(reqHeaders), MultiMapUtils.unmodifiableMultiValuedMap(reqParameters));
 
             hookProcessor.process(eventType, body, context, endpoint);
-        } catch(BitbucketHookProcessorException e) {
+        } catch(BitbucketWebhookProcessorException e) {
             return HttpResponses.error(e.getHttpCode(), e.getMessage());
         }
         return HttpResponses.ok();
     }
 
-    private BitbucketHookProcessor getHookProcessor(Map<String, String> reqHeaders,
+    private BitbucketWebhookProcessor getHookProcessor(Map<String, String> reqHeaders,
                                                     MultiValuedMap<String, String> reqParameters) {
-        BitbucketHookProcessor hookProcessor;
+        BitbucketWebhookProcessor hookProcessor;
 
-        List<BitbucketHookProcessor> matchingProcessors = getHookProcessors()
+        List<BitbucketWebhookProcessor> matchingProcessors = getHookProcessors()
             .filter(processor -> processor.canHandle(Collections.unmodifiableMap(reqHeaders), MultiMapUtils.unmodifiableMultiValuedMap(reqParameters)))
             .toList();
         if (matchingProcessors.isEmpty()) {
             logger.warning(() -> "No processor found for the incoming Bitbucket hook. Skipping.");
-            throw new BitbucketHookProcessorException(HttpServletResponse.SC_BAD_REQUEST, "No processor found that supports this event. Refer to the user documentation on how configure the webHook in Bitbucket at https://github.com/jenkinsci/bitbucket-branch-source-plugin/blob/master/docs/USER_GUIDE.adoc#webhooks-registering");
+            throw new BitbucketWebhookProcessorException(HttpServletResponse.SC_BAD_REQUEST, "No processor found that supports this event. Refer to the user documentation on how configure the webHook in Bitbucket at https://github.com/jenkinsci/bitbucket-branch-source-plugin/blob/master/docs/USER_GUIDE.adoc#webhooks-registering");
         } else if (matchingProcessors.size() > 1) {
             String processors = StringUtils.joinWith("\n- ", matchingProcessors.stream()
                 .map(p -> p.getClass().getName())
                 .toList());
             logger.severe(() -> "More processors found that handle the incoming Bitbucket hook:\n" + processors);
-            throw new BitbucketHookProcessorException(HttpServletResponse.SC_CONFLICT, "More processors found that handle the incoming Bitbucket hook.");
+            throw new BitbucketWebhookProcessorException(HttpServletResponse.SC_CONFLICT, "More processors found that handle the incoming Bitbucket hook.");
         } else {
             hookProcessor = matchingProcessors.get(0);
             logger.fine(() -> "Hook processor " + hookProcessor.getClass().getName() + " found.");
         }
         return hookProcessor;
     }
 
-    /*test*/ Stream<BitbucketHookProcessor> getHookProcessors() {
-        return ExtensionList.lookup(BitbucketHookProcessor.class).stream();
+    /*test*/ Stream<BitbucketWebhookProcessor> getHookProcessors() {
+        return ExtensionList.lookup(BitbucketWebhookProcessor.class).stream();
     }
 
     private MultiValuedMap<String, String> getParameters(StaplerRequest2 req) {

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/endpoint/AbstractBitbucketEndpoint.java

@@ -26,13 +26,15 @@
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketAuthenticator;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpointDescriptor;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhook;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketCredentialsUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.URLUtils;
 import com.cloudbees.plugins.credentials.common.StandardCredentials;
 import com.cloudbees.plugins.credentials.common.StandardUsernamePasswordCredentials;
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.Util;
+import java.util.Objects;
 import jenkins.authentication.tokens.api.AuthenticationTokens;
 import jenkins.model.Jenkins;
 import org.apache.commons.lang3.StringUtils;
@@ -60,6 +62,9 @@ public abstract class AbstractBitbucketEndpoint implements BitbucketEndpoint {
     @CheckForNull
     private String credentialsId;
 
+    @NonNull
+    private BitbucketWebhook webhook;
+
     /**
      * {@code true} if and only if Jenkins have to verify the signature of all incoming hooks.
      */
@@ -267,4 +272,13 @@ public BitbucketAuthenticator authenticator() {
     public BitbucketEndpointDescriptor getDescriptor() {
         return (BitbucketEndpointDescriptor) Jenkins.get().getDescriptorOrDie(getClass());
     }
+
+    public @NonNull BitbucketWebhook getWebhook() {
+        return webhook;
+    }
+
+    @DataBoundSetter
+    public void setWebhook(@NonNull BitbucketWebhook webhook) {
+        this.webhook = Objects.requireNonNull(webhook);
+    }
 }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/endpoint/BitbucketServerEndpoint.java

@@ -50,8 +50,6 @@
 import org.kohsuke.stapler.QueryParameter;
 import org.kohsuke.stapler.interceptor.RequirePOST;
 
-import static java.util.Objects.requireNonNull;
-
 /**
  * Represents a Bitbucket Server instance.
  *
@@ -74,9 +72,9 @@ public class BitbucketServerEndpoint extends AbstractBitbucketEndpoint {
 
     @NonNull
     public static BitbucketServerWebhookImplementation findWebhookImplementation(String serverURL) {
-        return BitbucketEndpointProvider.lookupEndpoint(serverURL, BitbucketServerEndpoint.class)
+        return /*BitbucketEndpointProvider.lookupEndpoint(serverURL, BitbucketServerEndpoint.class)
                 .map(BitbucketServerEndpoint::getWebhookImplementation)
-                .orElse(BitbucketServerWebhookImplementation.NATIVE);
+                .orElse(BitbucketServerWebhookImplementation.NATIVE);*/ null;
     }
 
     @NonNull
@@ -99,8 +97,8 @@ public static BitbucketServerVersion findServerVersion(String serverURL) {
     @NonNull
     private final String serverUrl;
 
-    @NonNull
-    private BitbucketServerWebhookImplementation webhookImplementation = BitbucketServerWebhookImplementation.NATIVE;
+//    @NonNull
+//    private BitbucketServerWebhookImplementation webhookImplementation = BitbucketServerWebhookImplementation.NATIVE;
 
     /**
      * The server version for this endpoint.
@@ -243,9 +241,9 @@ public String getRepositoryURL(@NonNull String repoOwner, @NonNull String reposi
 
     @SuppressFBWarnings(value = "RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE", justification = "Only non-null after we set them here!")
     private Object readResolve() {
-        if (webhookImplementation == null) {
-            webhookImplementation = BitbucketServerWebhookImplementation.NATIVE;
-        }
+//        if (webhookImplementation == null) {
+//            webhookImplementation = BitbucketServerWebhookImplementation.NATIVE;
+//        }
         if (getBitbucketJenkinsRootUrl() != null) {
             setBitbucketJenkinsRootUrl(getBitbucketJenkinsRootUrl());
         }
@@ -256,15 +254,15 @@ private Object readResolve() {
         return this;
     }
 
-    @NonNull
-    public BitbucketServerWebhookImplementation getWebhookImplementation() {
-        return webhookImplementation;
-    }
+//    @NonNull
+//    public BitbucketServerWebhookImplementation getWebhookImplementation() {
+//        return webhookImplementation;
+//    }
 
-    @DataBoundSetter
-    public void setWebhookImplementation(@NonNull BitbucketServerWebhookImplementation webhookImplementation) {
-        this.webhookImplementation = requireNonNull(webhookImplementation);
-    }
+//    @DataBoundSetter
+//    public void setWebhookImplementation(@NonNull BitbucketServerWebhookImplementation webhookImplementation) {
+//        this.webhookImplementation = requireNonNull(webhookImplementation);
+//    }
 
     /**
      * Our descriptor.