feat(webhooks): add flyteplugins-webhooks-clickup

Receive ClickUp webhooks in Flyte. Implements the Provider contract from
flyteplugins-webhooks-core: which environment variable holds the secret, how to
verify a delivery, how to parse one into a WebhookEvent, plus typed constants
for every event ClickUp can send.

Runs the shared conformance check, which replays a real SAMPLE_DELIVERY through
verify and parse rather than trusting them to agree with each other.

Calling the ClickUp API is deliberately not this plugin's job.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VKZrTNjjWVzTZUxDFbn4Nk
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>

Author: cosmicBboy

plugins/webhooks/clickup/README.md

@@ -0,0 +1,69 @@
+# flyteplugins-webhooks-clickup
+
+Receive ClickUp webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-webhooks-core[app]" flyteplugins-webhooks-clickup
+```
+
+## Using it
+
+Hand `PROVIDER` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`:
+
+```python
+import flyte
+from flyteplugins.webhooks.core import DuplicateRun, WebhookAppEnvironment, idempotent_run
+from flyteplugins.webhooks.clickup import PROVIDER, events
+
+app_env = WebhookAppEnvironment(
+    name="clickup-webhooks",
+    providers=[PROVIDER],
+    secrets=[flyte.Secret("CLICKUP_WEBHOOK_SECRET", as_env_var="CLICKUP_WEBHOOK_SECRET")],
+)
+
+
+@app_env.on_event(events.Task.STATUS_UPDATED)
+async def handle(event):
+    import flyte.remote as remote
+
+    task = remote.Task.get(name="my-env.my_task", auto_version="latest")
+    try:
+        run = await idempotent_run.aio(task, key=event.dedupe_key(), resource=event.resource_id)
+    except DuplicateRun as exc:
+        return {"skipped": str(exc)}
+    return {"run": run.name}
+
+
+flyte.serve(app_env)
+```
+
+Handlers must `await idempotent_run.aio(...)`. The blocking form stalls the
+app's event loop, and ClickUp times deliveries out in seconds.
+
+One app can serve several products at once — hand it more than one `PROVIDER`.
+
+## Setup
+
+1. Store the secret and mount it on the app:
+   ```bash
+   flyte create secret CLICKUP_WEBHOOK_SECRET --value <secret>
+   ```
+2. Point ClickUp at `<app-url>/webhook/clickup`, from
+   Space Settings → Integrations → Webhooks (it shows the signing secret on creation).
+
+**Verification:** HMAC-SHA256 over the raw body (`X-Clickup-Signature`).
+
+The list id is at the top level on list-scoped events and on the nested task for task-scoped ones; the parser reads both.
+
+## Event constants
+
+`events` spells every event this plugin can dispatch, as `str` enums grouped by
+event type, so a typo fails at import rather than by silently never matching.
+Raw strings still work, for events the constants do not cover yet.
+
+## What this plugin does not do
+
+Call the ClickUp API. Use `httpx` — ClickUp ships no Python SDK, and its API is a handful of REST calls directly from your tasks — see
+`examples/external_saas_integrations`. This plugin owns only the part that is
+Flyte's: authenticating an inbound delivery and turning it into a run.

plugins/webhooks/clickup/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "flyteplugins-webhooks-clickup"
+dynamic = ["version"]
+description = "Receive ClickUp webhooks in Flyte."
+readme = "README.md"
+authors = [{ name = "Flyte Contributors" }]
+requires-python = ">=3.10"
+dependencies = ["flyteplugins-webhooks-core"]
+
+[build-system]
+requires = ["setuptools", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "httpx>=0.27",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["flyteplugins*"]
+
+[tool.setuptools_scm]
+root = "../../.."
+
+[tool.pytest.ini_options]
+norecursedirs = []
+log_cli = true
+log_cli_level = 20
+markers = []
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+branch = true
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "PLW", "YTT", "ASYNC", "C4", "T10", "EXE", "ISC", "LOG", "PIE", "Q", "RSE", "FLY", "PGH", "PLC", "PLE", "FURB", "RUF"]
+ignore = ["PGH003", "PLC0415"]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/*" = ["E402"]
+
+[tool.uv.sources]
+flyte = { path = "../../..", editable = true }
+flyteplugins-webhooks-core = { path = "../core", editable = true }

plugins/webhooks/clickup/src/flyteplugins/webhooks/clickup/__init__.py

@@ -0,0 +1,31 @@
+"""ClickUp webhooks for Flyte.
+
+Hand `PROVIDER` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`. Calling the ClickUp API is not this plugin's job —
+it is a handful of REST calls, so use `httpx` from your tasks. See
+`examples/external_saas_integrations`.
+"""
+
+import hashlib
+import hmac
+
+from . import events
+from ._provider import PROVIDER, parse, verify
+
+__all__ = ["PROVIDER", "SAMPLE_DELIVERY", "events", "parse", "verify"]
+
+
+def _sample_headers(body: bytes, secret: str) -> dict[str, str]:
+    return {"X-Clickup-Signature": hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()}
+
+
+#: A real `taskCreated` delivery, trimmed to the fields the parser reads.
+SAMPLE_DELIVERY = (
+    _sample_headers,
+    (
+        b'{"event": "taskCreated", "task_id": "abc123", "list_id": "9000",'
+        b' "webhook_id": "wh-000", "timestamp": 1700000000000,'
+        b' "task": {"id": "abc123", "name": "Fix the thing",'
+        b' "url": "https://app.clickup.com/t/abc123"}}'
+    ),
+)

plugins/webhooks/clickup/src/flyteplugins/webhooks/clickup/_provider.py

@@ -0,0 +1,52 @@
+"""ClickUp webhook verification and payload normalization."""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from flyteplugins.webhooks.core import (
+    Provider,
+    WebhookEvent,
+    constant_time_equals,
+    hex_hmac_sha256,
+    json_body,
+    lower_headers,
+)
+
+
+def verify(body: bytes, headers: Mapping[str, str], secret: str) -> bool:
+    """Verify the `X-Clickup-Signature` HMAC over the raw body."""
+    signature = lower_headers(headers).get("x-clickup-signature")
+    return bool(signature) and constant_time_equals(hex_hmac_sha256(secret, body), signature.strip())
+
+
+def parse(headers: Mapping[str, str], body: bytes) -> WebhookEvent:
+    """Normalize a ClickUp delivery into a `WebhookEvent`."""
+    payload = json_body(body)
+    task = payload.get("task") or {}
+    # ClickUp puts the list id at the top level on list-scoped events and only on
+    # the nested task for task-scoped ones; read both or a `scopes` allowlist
+    # cannot attribute task events.
+    list_id = payload.get("list_id") or (task.get("list") or {}).get("id")
+    task_id = payload.get("task_id") or task.get("id")
+    return WebhookEvent(
+        provider="clickup",
+        event_type=payload.get("event", "unknown"),
+        delivery_id=str(payload.get("webhook_id") or ""),
+        resource_id=str(task_id) if task_id is not None else None,
+        occurred_at=str(payload.get("timestamp")) if payload.get("timestamp") is not None else None,
+        scope=str(list_id) if list_id is not None else None,
+        title=task.get("name"),
+        url=task.get("url"),
+        payload=payload,
+    )
+
+
+#: The contract core needs to accept ClickUp webhooks.
+PROVIDER = Provider(
+    name="clickup",
+    secret_env="CLICKUP_WEBHOOK_SECRET",
+    verify=verify,
+    parse=parse,
+    setup_hint="Space Settings -> Integrations -> Webhooks",
+)

plugins/webhooks/clickup/src/flyteplugins/webhooks/clickup/events.py

@@ -0,0 +1,65 @@
+"""ClickUp webhook events. Names are flat — ClickUp sends no separate action."""
+
+from __future__ import annotations
+
+from flyteplugins.webhooks.core import EventType
+
+__all__ = ["Folder", "Goal", "KeyResult", "List", "Space", "Task"]
+
+
+class Task(EventType):
+    """Task events."""
+
+    CREATED = "taskCreated"
+    UPDATED = "taskUpdated"
+    DELETED = "taskDeleted"
+    PRIORITY_UPDATED = "taskPriorityUpdated"
+    STATUS_UPDATED = "taskStatusUpdated"
+    ASSIGNEE_UPDATED = "taskAssigneeUpdated"
+    DUE_DATE_UPDATED = "taskDueDateUpdated"
+    TAG_UPDATED = "taskTagUpdated"
+    MOVED = "taskMoved"
+    COMMENT_POSTED = "taskCommentPosted"
+    COMMENT_UPDATED = "taskCommentUpdated"
+    TIME_ESTIMATE_UPDATED = "taskTimeEstimateUpdated"
+    TIME_TRACKED_UPDATED = "taskTimeTrackedUpdated"
+
+
+class List(EventType):
+    """List events."""
+
+    CREATED = "listCreated"
+    UPDATED = "listUpdated"
+    DELETED = "listDeleted"
+
+
+class Folder(EventType):
+    """Folder events."""
+
+    CREATED = "folderCreated"
+    UPDATED = "folderUpdated"
+    DELETED = "folderDeleted"
+
+
+class Space(EventType):
+    """Space events."""
+
+    CREATED = "spaceCreated"
+    UPDATED = "spaceUpdated"
+    DELETED = "spaceDeleted"
+
+
+class Goal(EventType):
+    """Goal events."""
+
+    CREATED = "goalCreated"
+    UPDATED = "goalUpdated"
+    DELETED = "goalDeleted"
+
+
+class KeyResult(EventType):
+    """Key-result (goal target) events."""
+
+    CREATED = "keyResultCreated"
+    UPDATED = "keyResultUpdated"
+    DELETED = "keyResultDeleted"

plugins/webhooks/clickup/tests/test_clickup.py

@@ -0,0 +1,38 @@
+"""ClickUp-specific normalization, beyond conformance."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+
+from flyteplugins.webhooks.clickup import events, parse
+
+SECRET = "clickup-secret"
+
+
+def _parse(payload: dict):
+    body = json.dumps(payload).encode()
+    return parse({"X-Clickup-Signature": hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()}, body)
+
+
+def test_the_event_name_is_the_qualified_type():
+    assert _parse({"event": "taskStatusUpdated", "task_id": "t1"}).qualified_type == events.Task.STATUS_UPDATED
+
+
+def test_the_list_id_falls_back_to_the_nested_task():
+    """Task-scoped events carry it only there; a scopes allowlist needs it."""
+    event = _parse({"event": "taskCreated", "task_id": "t1", "task": {"id": "t1", "list": {"id": "l7"}}})
+    assert event.scope == "l7"
+
+
+def test_a_top_level_list_id_wins():
+    event = _parse({"event": "listCreated", "list_id": "l1", "task": {"list": {"id": "l7"}}})
+    assert event.scope == "l1"
+
+
+def test_later_updates_to_one_task_get_their_own_keys():
+    def update(timestamp: int):
+        return _parse({"event": "taskUpdated", "task_id": "t1", "timestamp": timestamp})
+
+    assert update(1700000000000).dedupe_key() != update(1700000009999).dedupe_key()

plugins/webhooks/clickup/tests/test_conformance.py

@@ -0,0 +1,16 @@
+"""Every provider plugin runs the same conformance check.
+
+CI fails here if this plugin drifts from the shared format: a verifier that
+raises instead of returning False, event constants that render as enum names, a
+sample delivery that no constant spells, an unstable dedupe key.
+"""
+
+from __future__ import annotations
+
+from flyteplugins.webhooks.core.testing import assert_provider_conforms
+
+import flyteplugins.webhooks.clickup as plugin
+
+
+def test_conformance():
+    assert_provider_conforms(plugin)