feat: Add webhook push functionality for bot message events (#1768)

* Initial plan

* Backend: Add webhook persistence model, service, API endpoints and message push functionality

Co-authored-by: RockChinQ <45992437+RockChinQ@users.noreply.github.com>

* Frontend: Rename API Keys to API Integration, add webhook management UI with tabs

Co-authored-by: RockChinQ <45992437+RockChinQ@users.noreply.github.com>

* Fix frontend linting issues and formatting

Co-authored-by: RockChinQ <45992437+RockChinQ@users.noreply.github.com>

* chore: perf ui in api integration dialog

* perf: webhook data pack structure

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: RockChinQ <45992437+RockChinQ@users.noreply.github.com>
Co-authored-by: Junyan Qin <rockchinq@gmail.com>

pkg/api/http/controller/groups/webhooks.py

@@ -0,0 +1,49 @@
+import quart
+
+from .. import group
+
+
+@group.group_class('webhooks', '/api/v1/webhooks')
+class WebhooksRouterGroup(group.RouterGroup):
+    async def initialize(self) -> None:
+        @self.route('', methods=['GET', 'POST'])
+        async def _() -> str:
+            if quart.request.method == 'GET':
+                webhooks = await self.ap.webhook_service.get_webhooks()
+                return self.success(data={'webhooks': webhooks})
+            elif quart.request.method == 'POST':
+                json_data = await quart.request.json
+                name = json_data.get('name', '')
+                url = json_data.get('url', '')
+                description = json_data.get('description', '')
+                enabled = json_data.get('enabled', True)
+
+                if not name:
+                    return self.http_status(400, -1, 'Name is required')
+                if not url:
+                    return self.http_status(400, -1, 'URL is required')
+
+                webhook = await self.ap.webhook_service.create_webhook(name, url, description, enabled)
+                return self.success(data={'webhook': webhook})
+
+        @self.route('/<int:webhook_id>', methods=['GET', 'PUT', 'DELETE'])
+        async def _(webhook_id: int) -> str:
+            if quart.request.method == 'GET':
+                webhook = await self.ap.webhook_service.get_webhook(webhook_id)
+                if webhook is None:
+                    return self.http_status(404, -1, 'Webhook not found')
+                return self.success(data={'webhook': webhook})
+
+            elif quart.request.method == 'PUT':
+                json_data = await quart.request.json
+                name = json_data.get('name')
+                url = json_data.get('url')
+                description = json_data.get('description')
+                enabled = json_data.get('enabled')
+
+                await self.ap.webhook_service.update_webhook(webhook_id, name, url, description, enabled)
+                return self.success()
+
+            elif quart.request.method == 'DELETE':
+                await self.ap.webhook_service.delete_webhook(webhook_id)
+                return self.success()

pkg/api/http/service/webhook.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import sqlalchemy
+
+from ....core import app
+from ....entity.persistence import webhook
+
+
+class WebhookService:
+    ap: app.Application
+
+    def __init__(self, ap: app.Application) -> None:
+        self.ap = ap
+
+    async def get_webhooks(self) -> list[dict]:
+        """Get all webhooks"""
+        result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(webhook.Webhook))
+
+        webhooks = result.all()
+        return [self.ap.persistence_mgr.serialize_model(webhook.Webhook, wh) for wh in webhooks]
+
+    async def create_webhook(self, name: str, url: str, description: str = '', enabled: bool = True) -> dict:
+        """Create a new webhook"""
+        webhook_data = {'name': name, 'url': url, 'description': description, 'enabled': enabled}
+
+        await self.ap.persistence_mgr.execute_async(sqlalchemy.insert(webhook.Webhook).values(**webhook_data))
+
+        # Retrieve the created webhook
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.select(webhook.Webhook).where(webhook.Webhook.url == url).order_by(webhook.Webhook.id.desc())
+        )
+        created_webhook = result.first()
+
+        return self.ap.persistence_mgr.serialize_model(webhook.Webhook, created_webhook)
+
+    async def get_webhook(self, webhook_id: int) -> dict | None:
+        """Get a specific webhook by ID"""
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.select(webhook.Webhook).where(webhook.Webhook.id == webhook_id)
+        )
+
+        wh = result.first()
+
+        if wh is None:
+            return None
+
+        return self.ap.persistence_mgr.serialize_model(webhook.Webhook, wh)
+
+    async def update_webhook(
+        self, webhook_id: int, name: str = None, url: str = None, description: str = None, enabled: bool = None
+    ) -> None:
+        """Update a webhook's metadata"""
+        update_data = {}
+        if name is not None:
+            update_data['name'] = name
+        if url is not None:
+            update_data['url'] = url
+        if description is not None:
+            update_data['description'] = description
+        if enabled is not None:
+            update_data['enabled'] = enabled
+
+        if update_data:
+            await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.update(webhook.Webhook).where(webhook.Webhook.id == webhook_id).values(**update_data)
+            )
+
+    async def delete_webhook(self, webhook_id: int) -> None:
+        """Delete a webhook"""
+        await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.delete(webhook.Webhook).where(webhook.Webhook.id == webhook_id)
+        )
+
+    async def get_enabled_webhooks(self) -> list[dict]:
+        """Get all enabled webhooks"""
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.select(webhook.Webhook).where(webhook.Webhook.enabled == True)
+        )
+
+        webhooks = result.all()
+        return [self.ap.persistence_mgr.serialize_model(webhook.Webhook, wh) for wh in webhooks]

pkg/core/app.py

@@ -6,6 +6,7 @@ import traceback
 import os
 
 from ..platform import botmgr as im_mgr
+from ..platform.webhook_pusher import WebhookPusher
 from ..provider.session import sessionmgr as llm_session_mgr
 from ..provider.modelmgr import modelmgr as llm_model_mgr
 from ..provider.tools import toolmgr as llm_tool_mgr
@@ -24,6 +25,7 @@ from ..api.http.service import bot as bot_service
 from ..api.http.service import knowledge as knowledge_service
 from ..api.http.service import mcp as mcp_service
 from ..api.http.service import apikey as apikey_service
+from ..api.http.service import webhook as webhook_service
 from ..discover import engine as discover_engine
 from ..storage import mgr as storagemgr
 from ..utils import logcache
@@ -45,6 +47,8 @@ class Application:
 
     platform_mgr: im_mgr.PlatformManager = None
 
+    webhook_pusher: WebhookPusher = None
+
     cmd_mgr: cmdmgr.CommandManager = None
 
     sess_mgr: llm_session_mgr.SessionManager = None
@@ -125,6 +129,8 @@ class Application:
 
     apikey_service: apikey_service.ApiKeyService = None
 
+    webhook_service: webhook_service.WebhookService = None
+
     def __init__(self):
         pass
 

pkg/core/stages/build_app.py

@@ -12,6 +12,7 @@ from ...provider.modelmgr import modelmgr as llm_model_mgr
 from ...provider.tools import toolmgr as llm_tool_mgr
 from ...rag.knowledge import kbmgr as rag_mgr
 from ...platform import botmgr as im_mgr
+from ...platform.webhook_pusher import WebhookPusher
 from ...persistence import mgr as persistencemgr
 from ...api.http.controller import main as http_controller
 from ...api.http.service import user as user_service
@@ -21,6 +22,7 @@ from ...api.http.service import bot as bot_service
 from ...api.http.service import knowledge as knowledge_service
 from ...api.http.service import mcp as mcp_service
 from ...api.http.service import apikey as apikey_service
+from ...api.http.service import webhook as webhook_service
 from ...discover import engine as discover_engine
 from ...storage import mgr as storagemgr
 from ...utils import logcache
@@ -93,6 +95,10 @@ class BuildAppStage(stage.BootingStage):
         await im_mgr_inst.initialize()
         ap.platform_mgr = im_mgr_inst
 
+        # Initialize webhook pusher
+        webhook_pusher_inst = WebhookPusher(ap)
+        ap.webhook_pusher = webhook_pusher_inst
+
         pipeline_mgr = pipelinemgr.PipelineManager(ap)
         await pipeline_mgr.initialize()
         ap.pipeline_mgr = pipeline_mgr
@@ -134,5 +140,8 @@ class BuildAppStage(stage.BootingStage):
         apikey_service_inst = apikey_service.ApiKeyService(ap)
         ap.apikey_service = apikey_service_inst
 
+        webhook_service_inst = webhook_service.WebhookService(ap)
+        ap.webhook_service = webhook_service_inst
+
         ctrl = controller.Controller(ap)
         ap.ctrl = ctrl

pkg/entity/persistence/webhook.py

@@ -0,0 +1,22 @@
+import sqlalchemy
+
+from .base import Base
+
+
+class Webhook(Base):
+    """Webhook for pushing bot events to external systems"""
+
+    __tablename__ = 'webhooks'
+
+    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    url = sqlalchemy.Column(sqlalchemy.String(1024), nullable=False)
+    description = sqlalchemy.Column(sqlalchemy.String(512), nullable=True, default='')
+    enabled = sqlalchemy.Column(sqlalchemy.Boolean, nullable=False, default=True)
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, server_default=sqlalchemy.func.now())
+    updated_at = sqlalchemy.Column(
+        sqlalchemy.DateTime,
+        nullable=False,
+        server_default=sqlalchemy.func.now(),
+        onupdate=sqlalchemy.func.now(),
+    )

pkg/platform/botmgr.py

@@ -13,6 +13,7 @@ from ..entity.persistence import bot as persistence_bot
 from ..entity.errors import platform as platform_errors
 
 from .logger import EventLogger
+from .webhook_pusher import WebhookPusher
 
 import langbot_plugin.api.entities.builtin.provider.session as provider_session
 import langbot_plugin.api.entities.builtin.platform.events as platform_events
@@ -66,6 +67,14 @@ class RuntimeBot:
                 message_session_id=f'person_{event.sender.id}',
             )
 
+            # Push to webhooks
+            if hasattr(self.ap, 'webhook_pusher') and self.ap.webhook_pusher:
+                asyncio.create_task(
+                    self.ap.webhook_pusher.push_person_message(
+                        event, self.bot_entity.uuid, adapter.__class__.__name__
+                    )
+                )
+
             await self.ap.query_pool.add_query(
                 bot_uuid=self.bot_entity.uuid,
                 launcher_type=provider_session.LauncherTypes.PERSON,
@@ -91,6 +100,14 @@ class RuntimeBot:
                 message_session_id=f'group_{event.group.id}',
             )
 
+            # Push to webhooks
+            if hasattr(self.ap, 'webhook_pusher') and self.ap.webhook_pusher:
+                asyncio.create_task(
+                    self.ap.webhook_pusher.push_group_message(
+                        event, self.bot_entity.uuid, adapter.__class__.__name__
+                    )
+                )
+
             await self.ap.query_pool.add_query(
                 bot_uuid=self.bot_entity.uuid,
                 launcher_type=provider_session.LauncherTypes.GROUP,

pkg/platform/webhook_pusher.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import aiohttp
+import uuid
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..core import app
+
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+
+
+class WebhookPusher:
+    """Push bot events to configured webhooks"""
+
+    ap: app.Application
+    logger: logging.Logger
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+        self.logger = self.ap.logger
+
+    async def push_person_message(self, event: platform_events.FriendMessage, bot_uuid: str, adapter_name: str) -> None:
+        """Push person message event to webhooks"""
+        try:
+            webhooks = await self.ap.webhook_service.get_enabled_webhooks()
+            if not webhooks:
+                return
+
+            # Build payload
+            payload = {
+                'uuid': str(uuid.uuid4()),  # unique id for the event
+                'event_type': 'bot.person_message',
+                'data': {
+                    'bot_uuid': bot_uuid,
+                    'adapter_name': adapter_name,
+                    'sender': {
+                        'id': str(event.sender.id),
+                        'name': getattr(event.sender, 'name', ''),
+                    },
+                    'message': event.message_chain.model_dump(),
+                    'timestamp': event.time if hasattr(event, 'time') else None,
+                },
+            }
+
+            # Push to all webhooks asynchronously
+            tasks = [self._push_to_webhook(webhook['url'], payload) for webhook in webhooks]
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        except Exception as e:
+            self.logger.error(f'Failed to push person message to webhooks: {e}')
+
+    async def push_group_message(self, event: platform_events.GroupMessage, bot_uuid: str, adapter_name: str) -> None:
+        """Push group message event to webhooks"""
+        try:
+            webhooks = await self.ap.webhook_service.get_enabled_webhooks()
+            if not webhooks:
+                return
+
+            # Build payload
+            payload = {
+                'uuid': str(uuid.uuid4()),  # unique id for the event
+                'event_type': 'bot.group_message',
+                'data': {
+                    'bot_uuid': bot_uuid,
+                    'adapter_name': adapter_name,
+                    'group': {
+                        'id': str(event.group.id),
+                        'name': getattr(event.group, 'name', ''),
+                    },
+                    'sender': {
+                        'id': str(event.sender.id),
+                        'name': getattr(event.sender, 'name', ''),
+                    },
+                    'message': event.message_chain.model_dump(),
+                    'timestamp': event.time if hasattr(event, 'time') else None,
+                },
+            }
+
+            # Push to all webhooks asynchronously
+            tasks = [self._push_to_webhook(webhook['url'], payload) for webhook in webhooks]
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        except Exception as e:
+            self.logger.error(f'Failed to push group message to webhooks: {e}')
+
+    async def _push_to_webhook(self, url: str, payload: dict) -> None:
+        """Push payload to a single webhook URL"""
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    url,
+                    json=payload,
+                    headers={'Content-Type': 'application/json'},
+                    timeout=aiohttp.ClientTimeout(total=15),
+                ) as response:
+                    if response.status >= 400:
+                        self.logger.warning(f'Webhook {url} returned status {response.status}')
+                    else:
+                        self.logger.debug(f'Successfully pushed to webhook {url}')
+        except asyncio.TimeoutError:
+            self.logger.warning(f'Timeout pushing to webhook {url}')
+        except Exception as e:
+            self.logger.warning(f'Error pushing to webhook {url}: {e}')