zulip/zerver/webhooks/trello/doc.html

<p>
    This webhook integration for Trello is the recommended way to
    integrate with Trello, and should support all the features of
    the <a href="#trello-plugin">legacy Trello cron-based
    integration</a>.
</p>

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

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

<p>
    Before you create a webhook,
    you'll need to follow the steps below to get an <b>APPLICATION_KEY</b>, and a <b>UserToken</b>,
    and to fetch the board's <b>idModel</b>.
</p>

<p>
    To generate the <b>APPLICATION_KEY</b>, open this URL in your web browser:<br/>
    <code>https://trello.com/1/appkey/generate</code>.
</p>

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

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

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

<p>
    Now you have the ingredients to create your webhook.
    Send a <code>POST</code> request to this URL with this data:
    <code>https://api.trello.com/1/tokens/&ltUserToken&gt/webhooks/?key=&ltAPPLICATION_KEY&gt</code>
</p>
<pre>{
    "description": "Webhook for Zulip integration",
    "callbackURL": "&ltURL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP&gt",
    "idModel": "&ltID_MODEL&gt",
}
</pre>
    You can use <code>curl</code> to do this:<br/>
<pre>curl 'https://api.trello.com/1/tokens/&ltUserToken&gt/webhooks/?key=&ltAPPLICATION_KEY&gt'
-H 'Content-Type: application/json' -H 'Accept: application/json'
--data-binary $'{\n  "description": "Webhook for Zulip integration",\n  "callbackURL": "&ltURL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP&gt",\n  "idModel": "&ltID_MODEL&gt"\n}'
--compressed
</pre>
<p>
    The response from Trello should look like:<br/>
</p>
<pre>{
    "id": "&ltWEBHOOK_ID&gt",
    "description": "Webhook for Zulip integration",
    "idModel": "&ltID_MODEL&gt",
    "callbackURL": "&ltURL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP&gt",
    "active": true
}
</pre>
<p>
    Congratulations! You've created a webhook and your integration is live.
</p>

<p>
    When you make changes in on this board in Trello, you will
    receive Zulip notifications like this:
</p>
<p><img class="screenshot" src="/static/images/integrations/trello/001.png"/></p>