feat(webhooks): add flyteplugins-webhooks-clickup

Receive ClickUp webhooks in Flyte. Exports `ClickUpProvider`, a Provider subclass with
its defaults pre-wired, so wiring it up reads:

    WebhookAppEnvironment(providers=[ClickUpProvider()])

Implements the 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.

examples/clickup_webhooks.py runs with no ClickUp account at all — `--local` replays
the plugin's own SAMPLE_DELIVERY through the app, so you can watch a delivery
be verified, normalized, and dispatched before wiring anything up.

Runs the shared conformance check, which replays that same sample 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,83 @@
+# flyteplugins-webhooks-clickup
+
+Receive ClickUp webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-webhooks-core[app]" flyteplugins-webhooks-clickup
+```
+
+## Using it
+
+Hand a `ClickUpProvider()` 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 ClickUpProvider, events
+
+app_env = WebhookAppEnvironment(
+    name="clickup-webhooks",
+    providers=[ClickUpProvider()],
+    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 one provider per product.
+
+## Try it
+
+`examples/clickup_webhooks.py` runs two ways. The first needs no ClickUp account:
+
+```bash
+python examples/clickup_webhooks.py --local   # replay a real sample delivery in-process
+python examples/clickup_webhooks.py           # deploy the receiver to Flyte
+```
+
+`--local` posts this plugin's `SAMPLE_DELIVERY` through the app with FastAPI's
+test client, so you see a delivery verified, normalized, and dispatched — plus
+an unsigned one refused with a 401, and the same delivery replayed to show the
+dedupe key is stable.
+
+## 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/examples/clickup_webhooks.py

@@ -0,0 +1,123 @@
+"""Receive ClickUp webhooks in Flyte, and see one arrive without leaving your laptop.
+
+Two ways to run this. The second needs no ClickUp account at all:
+
+    python clickup_webhooks.py --local   # replay a real sample delivery in-process
+    python clickup_webhooks.py           # deploy the receiver to Flyte
+
+`--local` runs the app through FastAPI's test client and posts this plugin's
+`SAMPLE_DELIVERY` — a `taskCreated` delivery — signed with a throwaway secret. You see the
+delivery verified, normalized, and dispatched to a handler, which is the whole
+path a real webhook takes.
+
+To receive real events, deploy it and point ClickUp at `<app-url>/webhook/clickup`
+from Space Settings -> Integrations -> Webhooks.
+
+Setup for the real thing:
+    flyte create secret CLICKUP_WEBHOOK_SECRET --value <secret>
+
+ClickUp shows the signing secret once, when you create the webhook.
+"""
+
+import os
+import sys
+
+import flyte
+from flyteplugins.webhooks.core import WebhookAppEnvironment
+
+from flyteplugins.webhooks.clickup import DEFAULT_SECRET_ENV, SAMPLE_DELIVERY, ClickUpProvider, events
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
+    "flyteplugins-webhooks-core[app]", "flyteplugins-webhooks-clickup"
+)
+
+app_env = WebhookAppEnvironment(
+    name="clickup-webhooks",
+    providers=[ClickUpProvider()],
+    image=image,
+    secrets=[flyte.Secret(DEFAULT_SECRET_ENV, as_env_var=DEFAULT_SECRET_ENV)],
+)
+
+
+@app_env.on_event(events.Task.CREATED)
+async def on_primary(event):
+    """React to the event this plugin's sample delivery carries.
+
+    Returning a dict is enough to see the path working. To do real work, launch
+    a deployed task instead — see `launch_a_task` below.
+    """
+    return {
+        "saw": event.qualified_type,
+        "resource": event.resource_id,
+        "title": event.title,
+        # The key `idempotent_run` would dedupe on. Replaying the same delivery
+        # produces the same key, which is what makes a redelivery a no-op.
+        "dedupe_key": event.dedupe_key(),
+    }
+
+
+@app_env.on_event(events.Task.STATUS_UPDATED)
+async def on_secondary(event):
+    """A second handler, to show dispatch picking the right one per event."""
+    return {"saw": event.qualified_type, "resource": event.resource_id}
+
+
+async def launch_a_task(event):
+    """What a handler looks like once it does real work.
+
+    Not registered above, because it needs `clickup-tickets.triage_task` deployed first
+    and a Flyte backend to launch into. Wire it up with:
+
+        @app_env.on_event(events.Task.CREATED)
+
+    `idempotent_run` refuses to launch when a run carrying the same dedupe key
+    is already live or has succeeded, so ClickUp redelivering an event — which
+    it does on any non-2xx — never starts a second run.
+    """
+    import flyte.remote as remote
+    from flyteplugins.webhooks.core import DuplicateRun, idempotent_run
+
+    task = remote.Task.get(name="clickup-tickets.triage_task", auto_version="latest")
+    try:
+        # Always `.aio`: the blocking form stalls the app's event loop, and
+        # webhook senders time deliveries out in seconds.
+        run = await idempotent_run.aio(task, key=event.dedupe_key(), task_id=event.resource_id)
+    except DuplicateRun as exc:
+        return {"skipped": str(exc)}
+    return {"run": run.name}
+
+
+def _try_locally() -> None:
+    """Post this plugin's sample delivery to the app, in-process."""
+    from fastapi.testclient import TestClient
+
+    secret = os.environ.setdefault(DEFAULT_SECRET_ENV, "local-trial-secret")
+    build_headers, body = SAMPLE_DELIVERY
+    client = TestClient(app_env.app)
+
+    print("POST /webhook/clickup  (signed with a throwaway secret)")
+    response = client.post("/webhook/clickup", content=body, headers=build_headers(body, secret))
+    print(f"  {response.status_code}  {response.json()}\n")
+
+    print("the same delivery again — note the identical dedupe_key:")
+    again = client.post("/webhook/clickup", content=body, headers=build_headers(body, secret))
+    print(f"  {again.status_code}  {again.json()}\n")
+
+    print("an unsigned delivery is refused:")
+    bad = client.post("/webhook/clickup", content=body, headers={})
+    print(f"  {bad.status_code}  {bad.json()}\n")
+
+    print("normalized events the app has seen:")
+    for seen in client.get("/api/events").json():
+        print(f"  {seen['provider']}  {seen['qualified_type']}  resource={seen['resource_id']}")
+
+
+if __name__ == "__main__":
+    if "--local" in sys.argv:
+        _try_locally()
+    else:
+        flyte.init_from_config()
+        handle = flyte.serve(app_env)
+        handle.activate(wait=True)
+        print(f"Dashboard ready at {handle.endpoint}")
+        print(f"Point ClickUp at {handle.endpoint}/webhook/clickup")

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 a `ClickUpProvider()` 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 DEFAULT_SECRET_ENV, ClickUpProvider, parse, verify
+
+__all__ = ["DEFAULT_SECRET_ENV", "SAMPLE_DELIVERY", "ClickUpProvider", "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,71 @@
+"""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,
+)
+
+#: Environment variable this provider reads its secret from by default.
+DEFAULT_SECRET_ENV = "CLICKUP_WEBHOOK_SECRET"
+
+
+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,
+    )
+
+
+class ClickUpProvider(Provider):
+    """ClickUp's webhook provider, with its defaults pre-wired.
+
+    ```python
+    from flyteplugins.webhooks.core import WebhookAppEnvironment
+    from flyteplugins.webhooks.clickup import ClickUpProvider
+
+    app_env = WebhookAppEnvironment(name="webhooks", providers=[ClickUpProvider()])
+    ```
+
+    Args:
+        secret_env: Environment variable holding the secret, mounted from a
+            `flyte.Secret`. Override only if you store it under a non-standard
+            name; the default is what the docs and examples assume.
+    """
+
+    def __init__(self, *, secret_env: str = DEFAULT_SECRET_ENV) -> None:
+        super().__init__(
+            name="clickup",
+            secret_env=secret_env,
+            verify=verify,
+            parse=parse,
+            setup_hint="Space Settings -> Integrations -> Webhooks",
+        )