[openhabcloud] Adds webhook service (#20486)

* Adds webhook service

Signed-off-by: Dan Cunningham <dan@digitaldan.com>

Author: digitaldan

bundles/org.openhab.io.openhabcloud/src/main/java/org/openhab/io/openhabcloud/WebhookService.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2010-2026 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.io.openhabcloud;
+
+import java.util.concurrent.CompletableFuture;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * Service interface for requesting webhook URLs from the openHAB Cloud.
+ *
+ * Other bindings can consume this service via OSGi {@code @Reference} to obtain
+ * publicly-reachable webhook URLs. When an external service calls the webhook URL,
+ * the cloud proxies the request to the specified local path on this openHAB instance.
+ *
+ * <p>
+ * Usage example:
+ *
+ * <pre>
+ * {@code @Reference(cardinality = ReferenceCardinality.OPTIONAL, policy = ReferencePolicy.DYNAMIC)}
+ * protected void setWebhookService(WebhookService service) {
+ *     this.webhookService = service;
+ * }
+ *
+ * // In initialize():
+ * webhookService.requestWebhook("/myBinding/callback")
+ *     .thenAccept(url -> externalApi.registerCallback(url));
+ * </pre>
+ *
+ * @author Dan Cunningham - Initial contribution
+ */
+@NonNullByDefault
+public interface WebhookService {
+
+    /**
+     * Request a webhook URL for the given local path. The cloud service will generate
+     * a unique URL like {@code https://myopenhab.org/api/hooks/{uuid}} that proxies
+     * incoming requests to the specified local path on this openHAB instance.
+     *
+     * <p>
+     * This method is idempotent: calling it with the same {@code localPath} returns
+     * the same webhook URL and refreshes the 30-day TTL.
+     *
+     * @param localPath the local openHAB path to forward webhook requests to
+     *            (e.g., {@code "/rest/webhook/netatmo"})
+     * @return a {@link CompletableFuture} that completes with the full webhook URL,
+     *         or completes exceptionally if the cloud is not connected or registration fails
+     */
+    CompletableFuture<String> requestWebhook(String localPath);
+
+    /**
+     * Remove a previously registered webhook for the given local path.
+     *
+     * @param localPath the local openHAB path whose webhook should be removed
+     * @return a {@link CompletableFuture} that completes when the webhook is removed,
+     *         or completes exceptionally if the cloud is not connected or removal fails
+     */
+    CompletableFuture<Void> removeWebhook(String localPath);
+}

bundles/org.openhab.io.openhabcloud/src/main/java/org/openhab/io/openhabcloud/internal/CloudClient.java

@@ -27,13 +27,15 @@
 import java.util.Optional;
 import java.util.Set;
 import java.util.WeakHashMap;
+import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentLinkedDeque;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Function;
 import java.util.function.Supplier;
 
 import org.eclipse.jdt.annotation.Nullable;
@@ -510,14 +512,16 @@ private void handleRequestEvent(JSONObject data) {
 
             Iterator<String> queryIterator = requestQueryJson.keys();
             // Add query parameters to URI builder, if any
-            newPath += "?";
-            while (queryIterator.hasNext()) {
-                String queryName = queryIterator.next();
-                newPath += queryName;
-                newPath += "=";
-                newPath += URLEncoder.encode(requestQueryJson.getString(queryName), "UTF-8");
-                if (queryIterator.hasNext()) {
-                    newPath += "&";
+            if (queryIterator.hasNext()) {
+                newPath += "?";
+                while (queryIterator.hasNext()) {
+                    String queryName = queryIterator.next();
+                    newPath += queryName;
+                    newPath += "=";
+                    newPath += URLEncoder.encode(requestQueryJson.getString(queryName), "UTF-8");
+                    if (queryIterator.hasNext()) {
+                        newPath += "&";
+                    }
                 }
             }
             // Finally get the future request URI
@@ -870,6 +874,62 @@ public void sendItemUpdate(String itemName, String itemState) {
         }
     }
 
+    /**
+     * Register a webhook with the openHAB Cloud for the given local path.
+     *
+     * @param localPath the local path to forward webhook requests to
+     * @param future the future to complete with the webhook URL or an error
+     */
+    public void registerWebhook(String localPath, CompletableFuture<String> future) {
+        emitWebhookEvent("webhook:register", localPath, future, response -> response.getString("webhookUrl"),
+                "Webhook registration timed out");
+    }
+
+    /**
+     * Remove a webhook from the openHAB Cloud for the given local path.
+     *
+     * @param localPath the local path whose webhook should be removed
+     * @param future the future to complete when the webhook is removed or on error
+     */
+    public void removeWebhook(String localPath, CompletableFuture<Void> future) {
+        emitWebhookEvent("webhook:remove", localPath, future, response -> null, "Webhook removal timed out");
+    }
+
+    private <T> void emitWebhookEvent(String eventName, String localPath, CompletableFuture<T> future,
+            Function<JSONObject, T> successHandler, String timeoutMessage) {
+        if (!isConnected()) {
+            future.completeExceptionally(new IOException("Not connected to openHAB Cloud"));
+            return;
+        }
+        try {
+            JSONObject data = new JSONObject();
+            data.put("localPath", localPath);
+            socket.emit(eventName, data, (io.socket.client.Ack) args -> {
+                try {
+                    if (args == null || args.length == 0 || !(args[0] instanceof JSONObject)) {
+                        future.completeExceptionally(new IOException("Missing or invalid response from openHAB Cloud"));
+                        return;
+                    }
+                    JSONObject response = (JSONObject) args[0];
+                    if (response.optBoolean("success")) {
+                        future.complete(successHandler.apply(response));
+                    } else {
+                        future.completeExceptionally(new IOException(response.optString("error", "Unknown error")));
+                    }
+                } catch (JSONException | ClassCastException e) {
+                    future.completeExceptionally(new IOException("Invalid response from cloud", e));
+                }
+            });
+            scheduler.schedule(() -> {
+                if (!future.isDone()) {
+                    future.completeExceptionally(new IOException(timeoutMessage));
+                }
+            }, 30, TimeUnit.SECONDS);
+        } catch (JSONException e) {
+            future.completeExceptionally(new IOException("Failed to build webhook request", e));
+        }
+    }
+
     /**
      * Returns true if openHAB Cloud connection is active
      */

bundles/org.openhab.io.openhabcloud/src/main/java/org/openhab/io/openhabcloud/internal/CloudService.java

@@ -22,6 +22,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.CompletableFuture;
 
 import org.eclipse.jdt.annotation.Nullable;
 import org.eclipse.jetty.client.HttpClient;
@@ -49,6 +50,7 @@
 import org.openhab.core.types.TypeParser;
 import org.openhab.core.util.StringUtils;
 import org.openhab.io.openhabcloud.NotificationAction;
+import org.openhab.io.openhabcloud.WebhookService;
 import org.osgi.framework.BundleContext;
 import org.osgi.framework.Constants;
 import org.osgi.service.component.annotations.Activate;
@@ -66,11 +68,11 @@
  * @author Kai Kreuzer - migrated code to new Jetty client and ESH APIs
  * @author Dan Cunningham - Extended notification enhancements
  */
-@Component(service = { CloudService.class, EventSubscriber.class,
-        ActionService.class }, configurationPid = "org.openhab.openhabcloud", property = Constants.SERVICE_PID
+@Component(service = { CloudService.class, EventSubscriber.class, ActionService.class,
+        WebhookService.class }, configurationPid = "org.openhab.openhabcloud", property = Constants.SERVICE_PID
                 + "=org.openhab.openhabcloud")
 @ConfigurableService(category = "io", label = "openHAB Cloud", description_uri = CloudService.CONFIG_URI)
-public class CloudService implements ActionService, CloudClientListener, EventSubscriber {
+public class CloudService implements ActionService, CloudClientListener, EventSubscriber, WebhookService {
 
     protected static final String CONFIG_URI = "io:openhabcloud";
 
@@ -325,6 +327,36 @@ protected void modified(Map<String, ?> config) {
         NotificationAction.setCloudService(this);
     }
 
+    @Override
+    public CompletableFuture<String> requestWebhook(String localPath) {
+        CompletableFuture<String> future = new CompletableFuture<>();
+        if (localPath.isBlank() || !localPath.startsWith("/")) {
+            future.completeExceptionally(new IllegalArgumentException("localPath must start with '/'"));
+            return future;
+        }
+        if (cloudClient != null && cloudClient.isConnected()) {
+            cloudClient.registerWebhook(localPath, future);
+        } else {
+            future.completeExceptionally(new IllegalStateException("Cloud connector is not connected"));
+        }
+        return future;
+    }
+
+    @Override
+    public CompletableFuture<Void> removeWebhook(String localPath) {
+        CompletableFuture<Void> future = new CompletableFuture<>();
+        if (localPath.isBlank() || !localPath.startsWith("/")) {
+            future.completeExceptionally(new IllegalArgumentException("localPath must start with '/'"));
+            return future;
+        }
+        if (cloudClient != null && cloudClient.isConnected()) {
+            cloudClient.removeWebhook(localPath, future);
+        } else {
+            future.completeExceptionally(new IllegalStateException("Cloud connector is not connected"));
+        }
+        return future;
+    }
+
     @Override
     public String getActionClassName() {
         return NotificationAction.class.getCanonicalName();