zulip/zerver/webhooks/trello/doc.md

This webhook integration for Trello is the recommended way to integrate with Trello, and should support all the features of the legacy Trello cron-based integration.

First, create the stream you'd like to use for Trello notifications, and subscribe all interested parties to this stream. We recommend the name trello.

Your webhook URL is: {{ external_api_uri_subdomain }}/v1/external/trello?api_key=abcdefgh&stream=trello where api_key is the API key of your Zulip bot, and stream is the stream name you want the notifications sent to.

Trello doesn't support creating webhooks on their website; you have to do it using their API. So before you create a webhook, you'll need to follow the steps below to get from Trello an APPLICATION_KEY, and a UserToken, and to fetch the board's idModel.

To generate the APPLICATION_KEY, open this URL in your web browser: https://trello.com/1/appkey/generate.

To generate a read access token, fill in and open this URL in the browser while logged into your Trello account: https://trello.com/1/authorize?key=<APPLICATION_KEY>&name=Issue+Manager&expiration=never&response_type=token&scope=read You will receive your UserToken. Note it.

Within the the board URL, you can find the TRELLO_BOARD_SHORT_ID. The Trello URL format is: https://trello.com/b/TRELLO_BOARD_SHORT_ID/boardName.

Now you have the APPLICATION_KEY, UserToken and TRELLO_BOARD_SHORT_ID. Construct this URL and open it in your web browser: https://api.trello.com/1/board/<TRELLO_BOARD_SHORT_ID>?key=<APPLICATION_KEY>&token=<UserToken> You'll receive some JSON. Within that, find the id value. That's your idModel; note it.

Now you have all the ingredients you need. To actually create the Trello webhook, you will need to send an HTTP POST request to the trello API webhook endpoint (https://api.trello.com/1/tokens/<UserToken>/webhooks/?key=<APPLICATION_KEY>) with the following data:

{
"description": "Webhook for Zulip integration",
"callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",
"idModel": "<ID_MODEL>",
}

You can do this using the curl program as follows:

curl 'https://api.trello.com/1/tokens/<UserToken>/webhooks/?key=<APPLICATION_KEY>'
-H 'Content-Type: application/json' -H 'Accept: application/json'
--data-binary $'{\n  "description": "Webhook for Zulip integration",\n  "callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",\n  "idModel": "<ID_MODEL>"\n}'
--compressed

The response from Trello should look like:

{
"id": "<WEBHOOK_ID>",
"description": "Webhook for Zulip integration",
"idModel": "<ID_MODEL>",
"callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",
"active": true
}

Congratulations! You've created a webhook and your integration is live.

When you make changes in on this board in Trello, you will receive Zulip notifications like this: