integrations: Add ClickUp integration.

[PieterCK]

Creates an incoming webhook integration for ClickUp. The main use case is getting notifications when new ClickUp items such as task, list, folder, space, goals are created, updated, or deleted.

Fixes #26529.
CZO thread

Notes:

• This integration also requires a helper script called zulip_clickup.py for now. similar to that of Trello's.
• This integration callsback to ClickUp's API endpoint to request detailed informations about their items. To do that, their API KEY is appended as a query in the integration URL generated by our bot as part of the webhook endpoint by the zulip_clickup.py script. This method of storing third party API KEY for integration callbacks is subject to change (Add support for incoming webhooks with a callback to the third-party server #10907).

Screenshots and screen captures:

• Screenshots of ClickUp notification in Zulip:

• Task Created
  
• Task Deleted
  
• Task Updated: Rename Task
  
• Task Updated: Priority Change
  
• Task Updated: Status Change
  
• Task Updated: Add Asignee
  
• Updated: Time Spent Change
  
• Task Updated: Due Date Change
  
• Task Updated: New Comment
  
• Task Updated: Task Moved
  
• List Created
  
• List Deleted
  
• List Updated: Rename List
  
• Space Created
  
• Space Updated: Rename Space
  

• zulip_clickup.py walkthrough:

# execute zulip_clickup.py command:
python3 zulip_clickup.py --clickup-team-id 123123123 --clickup-client-id V0COEU8DR93219J5KG6SDGIC2CQQFQOLP --clickup-client-secret 
TVIAY3SGJZR76IAAOLJ1231W1FZP6YAK1E2LAORWKTORYU30VC2QJ65Y0U

Screencast from 21-03-24 22:36:35.webm
PR for the integration script: PR#824

Self-review checklist

• Self-reviewed the changes for clarity and maintainability
  (variable names, code reuse, readability, etc.).

Communicate decisions, questions, and potential concerns.

• Explains differences from previous plans (e.g., issue description).
• Highlights technical choices and bugs encountered.
• Calls out remaining decisions and concerns.
• Automated tests verify logic where appropriate.

Individual commits are ready for review (see commit discipline).

• Each commit is a coherent idea.
• Commit message(s) explain reasoning and motivation for changes.

Completed manual review and testing of the following:

• Visual appearance of the changes.
• Responsiveness and internationalization.
• Strings and tooltips.
• End-to-end functionality of buttons, interactions and flows.
• Corner cases, error conditions, and easily imagined bugs.

[PieterCK]

@zulipbot add "area: integrations" "documentation review" "maintainer review"

[zulipbot]

Hello @zulip/server-integrations members, this pull request was labeled with the "area: integrations" label, so you may want to check it out!

[PieterCK]

Update: added more tests to 100% coverage.

@timabbott
Hi Tim, hope you're not too busy with GSOC stuff and other issues. Would you mind giving a quick follow up for my PR? Thank you!

[PieterCK]

Update: Adjusted the doc format to better follow changes in #29592

[laurynmm]

@PieterCK - Thanks for all the work on this integration! I did a review of the documentation part of these changes only.

Let me know if you have any questions about my feedback comments. Overall it looks pretty good and follows our new structure for integration docs.

One general change I'd make is to reorder the instructions to follow an order more like the one we use in the Trello integration doc:

• Set up the Zulip bot/URL
• Get the ClickUp information
• Download the python script and run it

And as far as formatting in these files, we usually leave an empty line after headers and include brackets in the documentation pages, so instead of ...

![](image_location)
# Header
* text
{tip}

it would be ...

![](image_location)

# Header

* text

{tip}

[PieterCK]

@laurynmm thanks for the feedbacks! Here's what the doc currently looks like:

If there are any more changes you'd like to suggest, feel free to leave another comment!

[alya]

@PieterCK Looks like there are some test failures to fix for this PR to be ready for the next round of review.

[PieterCK]

@PieterCK Looks like there are some test failures to fix for this PR to be ready for the next round of review.

Fixed it. Looking forward for your review 👍

[laurynmm]

@PieterCK - I did another pass on the documentation updates for this new integration. Let me know if you have any questions!

@timabbott - Let me know if you want me to do a review of the integration implementation.

[laurynmm]

I'd add a line break here for readability.

[laurynmm]

This file was renamed to create-channel.md.

[laurynmm]

I'd drop "button" at the end of this sentence.

[laurynmm]

I think you want a comma at the end of this line instead of a period.

[laurynmm]

Is there a reason two screenshots of messages are included in these changes? We can probably just have one for the documentation.

[PieterCK]

Constant variables are declared in clickup/__init__.py and not in view.py to avoid circular import because api_endpoints.py also uses a common constant variable; EventItemType.

[PieterCK]

Thank you for dropping another set of reviews for the doc page here, Lauryn. I've addressed them and also implemented some of the changes you suggested from the New Relic PR, where applicable.

[PieterCK]

@kennethnrk Hello Kenneth, could you please review this PR? Thank you!

@zulipbot label "buddy review"

[kennethnrk]

@PieterCK I'm unable to manually test this integration, I keep getting a response saying bad request.

Is it because I don't have a valid clickup team_id?

[PieterCK]

Yeah, this integration is a bit different from the other ones because ClickUp doesn't provide complete human-readable data in most of their payload.

To make things worse, they don't have a user-friendly UI or workflow to set up webhooks. Instead, you have to make API calls to their API endpoints to register the webhook integration ( Zulip endpoint URL & which events). To get the API keys to access their APIs, you must go through their OAuth flow.

This is the purpose of the helper script I submitted at this PR. It lives in the python-zulip-api repo and is required to integrate Zulip with ClickUp. For reference, our Trello integration follows a similar procedure to be integrated, and I largely followed that process for this script.

In addition to registering our webhook endpoint with ClickUp, this script has another function: appending a couple of variables to the user's webhook URL query. One of these variables is the team_id that you mentioned, and the other is the ClickUp API key I mentioned earlier. These variables will be used in the main Zulip codebase to do callbacks to ClickUp API endpoints and get additional context for the webhook payloads.

That is why our current tool wasn't able to test the integration because the webhook URL it uses doesn't have the team_id and clickup_api_key as expected. Even if it has those the integration would attempt to call ClickUp API endpoints using dummy credentials (team_id & API key) and would fail. To do manual test, I think you have to actually connect the webhook to the ClickUp using tools like ultrahook...

This whole PR is actually the first PR that I've submitted to Zulip, it is quite hefty and complicated. If I were to re-do it, I'd split it into a few commits the first one being a very rudimentary integration without callbacks and thus simpler notifications just so that it is easier to be tested and partially merged, then add the more complicated features like callbacks and detailed notifications in separate commits following that. This is also a suggestion my mentor @sbansal1999 endorsed. I think I will do it, but given the cost of such refactoring and the priority of this PR, this task would find itself near the bottom of my TODO list...

For now, I don't think you have to go through all that hassle to test the integration. It would already be very helpful if I could get a second pair of eyes to review the code styling and overall logic of the PR. @kennethnrk @sbansal1999 what do you guys think?