feat: add board webhook configuration and payload models
This commit is contained in:
Abhimanyu Saharan
451
backend/app/api/board_webhooks.py
Normal file
451
backend/app/api/board_webhooks.py
Normal file
@@ -0,0 +1,451 @@
|
||||
"""Board webhook configuration and inbound payload ingestion endpoints."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from typing import TYPE_CHECKING
|
||||
from uuid import UUID
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, Request, status
|
||||
from sqlmodel import col, select
|
||||
|
||||
from app.api.deps import get_board_for_user_read, get_board_for_user_write, get_board_or_404
|
||||
from app.core.config import settings
|
||||
from app.core.time import utcnow
|
||||
from app.db import crud
|
||||
from app.db.pagination import paginate
|
||||
from app.db.session import get_session
|
||||
from app.models.agents import Agent
|
||||
from app.models.board_memory import BoardMemory
|
||||
from app.models.board_webhook_payloads import BoardWebhookPayload
|
||||
from app.models.board_webhooks import BoardWebhook
|
||||
from app.schemas.board_webhooks import (
|
||||
BoardWebhookCreate,
|
||||
BoardWebhookIngestResponse,
|
||||
BoardWebhookPayloadRead,
|
||||
BoardWebhookRead,
|
||||
BoardWebhookUpdate,
|
||||
)
|
||||
from app.schemas.common import OkResponse
|
||||
from app.schemas.pagination import DefaultLimitOffsetPage
|
||||
from app.services.openclaw.gateway_dispatch import GatewayDispatchService
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from collections.abc import Sequence
|
||||
|
||||
from fastapi_pagination.limit_offset import LimitOffsetPage
|
||||
from sqlmodel.ext.asyncio.session import AsyncSession
|
||||
|
||||
from app.models.boards import Board
|
||||
|
||||
router = APIRouter(prefix="/boards/{board_id}/webhooks", tags=["board-webhooks"])
|
||||
SESSION_DEP = Depends(get_session)
|
||||
BOARD_USER_READ_DEP = Depends(get_board_for_user_read)
|
||||
BOARD_USER_WRITE_DEP = Depends(get_board_for_user_write)
|
||||
BOARD_OR_404_DEP = Depends(get_board_or_404)
|
||||
PAYLOAD_PREVIEW_MAX_CHARS = 1600
|
||||
|
||||
|
||||
def _webhook_endpoint_path(board_id: UUID, webhook_id: UUID) -> str:
|
||||
return f"/api/v1/boards/{board_id}/webhooks/{webhook_id}"
|
||||
|
||||
|
||||
def _webhook_endpoint_url(endpoint_path: str) -> str | None:
|
||||
base_url = settings.base_url.rstrip("/")
|
||||
if not base_url:
|
||||
return None
|
||||
return f"{base_url}{endpoint_path}"
|
||||
|
||||
|
||||
def _to_webhook_read(webhook: BoardWebhook) -> BoardWebhookRead:
|
||||
endpoint_path = _webhook_endpoint_path(webhook.board_id, webhook.id)
|
||||
return BoardWebhookRead(
|
||||
id=webhook.id,
|
||||
board_id=webhook.board_id,
|
||||
description=webhook.description,
|
||||
enabled=webhook.enabled,
|
||||
endpoint_path=endpoint_path,
|
||||
endpoint_url=_webhook_endpoint_url(endpoint_path),
|
||||
created_at=webhook.created_at,
|
||||
updated_at=webhook.updated_at,
|
||||
)
|
||||
|
||||
|
||||
def _to_payload_read(payload: BoardWebhookPayload) -> BoardWebhookPayloadRead:
|
||||
return BoardWebhookPayloadRead.model_validate(payload, from_attributes=True)
|
||||
|
||||
|
||||
def _coerce_webhook_items(items: Sequence[object]) -> list[BoardWebhook]:
|
||||
values: list[BoardWebhook] = []
|
||||
for item in items:
|
||||
if not isinstance(item, BoardWebhook):
|
||||
msg = "Expected BoardWebhook items from paginated query"
|
||||
raise TypeError(msg)
|
||||
values.append(item)
|
||||
return values
|
||||
|
||||
|
||||
def _coerce_payload_items(items: Sequence[object]) -> list[BoardWebhookPayload]:
|
||||
values: list[BoardWebhookPayload] = []
|
||||
for item in items:
|
||||
if not isinstance(item, BoardWebhookPayload):
|
||||
msg = "Expected BoardWebhookPayload items from paginated query"
|
||||
raise TypeError(msg)
|
||||
values.append(item)
|
||||
return values
|
||||
|
||||
|
||||
async def _require_board_webhook(
|
||||
session: AsyncSession,
|
||||
*,
|
||||
board_id: UUID,
|
||||
webhook_id: UUID,
|
||||
) -> BoardWebhook:
|
||||
webhook = (
|
||||
await session.exec(
|
||||
select(BoardWebhook)
|
||||
.where(col(BoardWebhook.id) == webhook_id)
|
||||
.where(col(BoardWebhook.board_id) == board_id),
|
||||
)
|
||||
).first()
|
||||
if webhook is None:
|
||||
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
|
||||
return webhook
|
||||
|
||||
|
||||
async def _require_board_webhook_payload(
|
||||
session: AsyncSession,
|
||||
*,
|
||||
board_id: UUID,
|
||||
webhook_id: UUID,
|
||||
payload_id: UUID,
|
||||
) -> BoardWebhookPayload:
|
||||
payload = (
|
||||
await session.exec(
|
||||
select(BoardWebhookPayload)
|
||||
.where(col(BoardWebhookPayload.id) == payload_id)
|
||||
.where(col(BoardWebhookPayload.board_id) == board_id)
|
||||
.where(col(BoardWebhookPayload.webhook_id) == webhook_id),
|
||||
)
|
||||
).first()
|
||||
if payload is None:
|
||||
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
|
||||
return payload
|
||||
|
||||
|
||||
def _decode_payload(
|
||||
raw_body: bytes,
|
||||
*,
|
||||
content_type: str | None,
|
||||
) -> dict[str, object] | list[object] | str | int | float | bool | None:
|
||||
if not raw_body:
|
||||
return {}
|
||||
|
||||
body_text = raw_body.decode("utf-8", errors="replace")
|
||||
normalized_content_type = (content_type or "").lower()
|
||||
should_parse_json = "application/json" in normalized_content_type
|
||||
if not should_parse_json:
|
||||
should_parse_json = body_text.startswith(("{", "[", '"')) or body_text in {"true", "false"}
|
||||
|
||||
if should_parse_json:
|
||||
try:
|
||||
parsed = json.loads(body_text)
|
||||
except json.JSONDecodeError:
|
||||
return body_text
|
||||
if isinstance(parsed, (dict, list, str, int, float, bool)) or parsed is None:
|
||||
return parsed
|
||||
return body_text
|
||||
|
||||
|
||||
def _captured_headers(request: Request) -> dict[str, str] | None:
|
||||
captured: dict[str, str] = {}
|
||||
for header, value in request.headers.items():
|
||||
normalized = header.lower()
|
||||
if normalized in {"content-type", "user-agent"} or normalized.startswith("x-"):
|
||||
captured[normalized] = value
|
||||
return captured or None
|
||||
|
||||
|
||||
def _payload_preview(
|
||||
value: dict[str, object] | list[object] | str | int | float | bool | None,
|
||||
) -> str:
|
||||
if isinstance(value, str):
|
||||
preview = value
|
||||
else:
|
||||
try:
|
||||
preview = json.dumps(value, indent=2, ensure_ascii=True)
|
||||
except TypeError:
|
||||
preview = str(value)
|
||||
if len(preview) <= PAYLOAD_PREVIEW_MAX_CHARS:
|
||||
return preview
|
||||
return f"{preview[: PAYLOAD_PREVIEW_MAX_CHARS - 3]}..."
|
||||
|
||||
|
||||
def _webhook_memory_content(
|
||||
*,
|
||||
webhook: BoardWebhook,
|
||||
payload: BoardWebhookPayload,
|
||||
) -> str:
|
||||
preview = _payload_preview(payload.payload)
|
||||
inspect_path = f"/api/v1/boards/{webhook.board_id}/webhooks/{webhook.id}/payloads/{payload.id}"
|
||||
return (
|
||||
"WEBHOOK PAYLOAD RECEIVED\n"
|
||||
f"Webhook ID: {webhook.id}\n"
|
||||
f"Payload ID: {payload.id}\n"
|
||||
f"Instruction: {webhook.description}\n"
|
||||
f"Inspect (admin API): {inspect_path}\n\n"
|
||||
"Payload preview:\n"
|
||||
f"{preview}"
|
||||
)
|
||||
|
||||
|
||||
async def _notify_lead_on_webhook_payload(
|
||||
*,
|
||||
session: AsyncSession,
|
||||
board: Board,
|
||||
webhook: BoardWebhook,
|
||||
payload: BoardWebhookPayload,
|
||||
) -> None:
|
||||
lead = (
|
||||
await Agent.objects.filter_by(board_id=board.id)
|
||||
.filter(col(Agent.is_board_lead).is_(True))
|
||||
.first(session)
|
||||
)
|
||||
if lead is None or not lead.openclaw_session_id:
|
||||
return
|
||||
|
||||
dispatch = GatewayDispatchService(session)
|
||||
config = await dispatch.optional_gateway_config_for_board(board)
|
||||
if config is None:
|
||||
return
|
||||
|
||||
payload_preview = _payload_preview(payload.payload)
|
||||
message = (
|
||||
"WEBHOOK EVENT RECEIVED\n"
|
||||
f"Board: {board.name}\n"
|
||||
f"Webhook ID: {webhook.id}\n"
|
||||
f"Payload ID: {payload.id}\n"
|
||||
f"Instruction: {webhook.description}\n\n"
|
||||
"Take action:\n"
|
||||
"1) Triage this payload against the webhook instruction.\n"
|
||||
"2) Create/update tasks as needed.\n"
|
||||
f"3) Reference payload ID {payload.id} in task descriptions.\n\n"
|
||||
"Payload preview:\n"
|
||||
f"{payload_preview}\n\n"
|
||||
"To inspect board memory entries:\n"
|
||||
f"GET /api/v1/agent/boards/{board.id}/memory?is_chat=false"
|
||||
)
|
||||
await dispatch.try_send_agent_message(
|
||||
session_key=lead.openclaw_session_id,
|
||||
config=config,
|
||||
agent_name=lead.name,
|
||||
message=message,
|
||||
deliver=False,
|
||||
)
|
||||
|
||||
|
||||
@router.get("", response_model=DefaultLimitOffsetPage[BoardWebhookRead])
|
||||
async def list_board_webhooks(
|
||||
board: Board = BOARD_USER_READ_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> LimitOffsetPage[BoardWebhookRead]:
|
||||
"""List configured webhooks for a board."""
|
||||
statement = (
|
||||
select(BoardWebhook)
|
||||
.where(col(BoardWebhook.board_id) == board.id)
|
||||
.order_by(col(BoardWebhook.created_at).desc())
|
||||
)
|
||||
|
||||
def _transform(items: Sequence[object]) -> Sequence[object]:
|
||||
webhooks = _coerce_webhook_items(items)
|
||||
return [_to_webhook_read(value) for value in webhooks]
|
||||
|
||||
return await paginate(session, statement, transformer=_transform)
|
||||
|
||||
|
||||
@router.post("", response_model=BoardWebhookRead)
|
||||
async def create_board_webhook(
|
||||
payload: BoardWebhookCreate,
|
||||
board: Board = BOARD_USER_WRITE_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> BoardWebhookRead:
|
||||
"""Create a new board webhook with a generated UUID endpoint."""
|
||||
webhook = BoardWebhook(
|
||||
board_id=board.id,
|
||||
description=payload.description,
|
||||
enabled=payload.enabled,
|
||||
)
|
||||
await crud.save(session, webhook)
|
||||
return _to_webhook_read(webhook)
|
||||
|
||||
|
||||
@router.get("/{webhook_id}", response_model=BoardWebhookRead)
|
||||
async def get_board_webhook(
|
||||
webhook_id: UUID,
|
||||
board: Board = BOARD_USER_READ_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> BoardWebhookRead:
|
||||
"""Get one board webhook configuration."""
|
||||
webhook = await _require_board_webhook(
|
||||
session,
|
||||
board_id=board.id,
|
||||
webhook_id=webhook_id,
|
||||
)
|
||||
return _to_webhook_read(webhook)
|
||||
|
||||
|
||||
@router.patch("/{webhook_id}", response_model=BoardWebhookRead)
|
||||
async def update_board_webhook(
|
||||
webhook_id: UUID,
|
||||
payload: BoardWebhookUpdate,
|
||||
board: Board = BOARD_USER_WRITE_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> BoardWebhookRead:
|
||||
"""Update board webhook description or enabled state."""
|
||||
webhook = await _require_board_webhook(
|
||||
session,
|
||||
board_id=board.id,
|
||||
webhook_id=webhook_id,
|
||||
)
|
||||
updates = payload.model_dump(exclude_unset=True)
|
||||
if updates:
|
||||
crud.apply_updates(webhook, updates)
|
||||
webhook.updated_at = utcnow()
|
||||
await crud.save(session, webhook)
|
||||
return _to_webhook_read(webhook)
|
||||
|
||||
|
||||
@router.delete("/{webhook_id}", response_model=OkResponse)
|
||||
async def delete_board_webhook(
|
||||
webhook_id: UUID,
|
||||
board: Board = BOARD_USER_WRITE_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> OkResponse:
|
||||
"""Delete a webhook and its stored payload rows."""
|
||||
webhook = await _require_board_webhook(
|
||||
session,
|
||||
board_id=board.id,
|
||||
webhook_id=webhook_id,
|
||||
)
|
||||
await crud.delete_where(
|
||||
session,
|
||||
BoardWebhookPayload,
|
||||
col(BoardWebhookPayload.webhook_id) == webhook.id,
|
||||
commit=False,
|
||||
)
|
||||
await session.delete(webhook)
|
||||
await session.commit()
|
||||
return OkResponse()
|
||||
|
||||
|
||||
@router.get(
|
||||
"/{webhook_id}/payloads", response_model=DefaultLimitOffsetPage[BoardWebhookPayloadRead]
|
||||
)
|
||||
async def list_board_webhook_payloads(
|
||||
webhook_id: UUID,
|
||||
board: Board = BOARD_USER_READ_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> LimitOffsetPage[BoardWebhookPayloadRead]:
|
||||
"""List stored payloads for one board webhook."""
|
||||
await _require_board_webhook(
|
||||
session,
|
||||
board_id=board.id,
|
||||
webhook_id=webhook_id,
|
||||
)
|
||||
statement = (
|
||||
select(BoardWebhookPayload)
|
||||
.where(col(BoardWebhookPayload.board_id) == board.id)
|
||||
.where(col(BoardWebhookPayload.webhook_id) == webhook_id)
|
||||
.order_by(col(BoardWebhookPayload.received_at).desc())
|
||||
)
|
||||
|
||||
def _transform(items: Sequence[object]) -> Sequence[object]:
|
||||
payloads = _coerce_payload_items(items)
|
||||
return [_to_payload_read(value) for value in payloads]
|
||||
|
||||
return await paginate(session, statement, transformer=_transform)
|
||||
|
||||
|
||||
@router.get("/{webhook_id}/payloads/{payload_id}", response_model=BoardWebhookPayloadRead)
|
||||
async def get_board_webhook_payload(
|
||||
webhook_id: UUID,
|
||||
payload_id: UUID,
|
||||
board: Board = BOARD_USER_READ_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> BoardWebhookPayloadRead:
|
||||
"""Get a single stored payload for one board webhook."""
|
||||
await _require_board_webhook(
|
||||
session,
|
||||
board_id=board.id,
|
||||
webhook_id=webhook_id,
|
||||
)
|
||||
payload = await _require_board_webhook_payload(
|
||||
session,
|
||||
board_id=board.id,
|
||||
webhook_id=webhook_id,
|
||||
payload_id=payload_id,
|
||||
)
|
||||
return _to_payload_read(payload)
|
||||
|
||||
|
||||
@router.post(
|
||||
"/{webhook_id}",
|
||||
response_model=BoardWebhookIngestResponse,
|
||||
status_code=status.HTTP_202_ACCEPTED,
|
||||
)
|
||||
async def ingest_board_webhook(
|
||||
request: Request,
|
||||
webhook_id: UUID,
|
||||
board: Board = BOARD_OR_404_DEP,
|
||||
session: AsyncSession = SESSION_DEP,
|
||||
) -> BoardWebhookIngestResponse:
|
||||
"""Open inbound webhook endpoint that stores payloads and nudges the board lead."""
|
||||
webhook = await _require_board_webhook(
|
||||
session,
|
||||
board_id=board.id,
|
||||
webhook_id=webhook_id,
|
||||
)
|
||||
if not webhook.enabled:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_410_GONE,
|
||||
detail="Webhook is disabled.",
|
||||
)
|
||||
|
||||
content_type = request.headers.get("content-type")
|
||||
payload_value = _decode_payload(
|
||||
await request.body(),
|
||||
content_type=content_type,
|
||||
)
|
||||
payload = BoardWebhookPayload(
|
||||
board_id=board.id,
|
||||
webhook_id=webhook.id,
|
||||
payload=payload_value,
|
||||
headers=_captured_headers(request),
|
||||
source_ip=request.client.host if request.client else None,
|
||||
content_type=content_type,
|
||||
)
|
||||
session.add(payload)
|
||||
memory = BoardMemory(
|
||||
board_id=board.id,
|
||||
content=_webhook_memory_content(webhook=webhook, payload=payload),
|
||||
tags=[
|
||||
"webhook",
|
||||
f"webhook:{webhook.id}",
|
||||
f"payload:{payload.id}",
|
||||
],
|
||||
source="webhook",
|
||||
is_chat=False,
|
||||
)
|
||||
session.add(memory)
|
||||
await session.commit()
|
||||
await _notify_lead_on_webhook_payload(
|
||||
session=session,
|
||||
board=board,
|
||||
webhook=webhook,
|
||||
payload=payload,
|
||||
)
|
||||
return BoardWebhookIngestResponse(
|
||||
board_id=board.id,
|
||||
webhook_id=webhook.id,
|
||||
payload_id=payload.id,
|
||||
)
|
||||
Reference in New Issue
Block a user