Publish documents to Slack

Webhooks

We'll use Slack's incoming webhooks, along with Portway's webhooks to post a document in Slack whenever it's published in Portway.

It's a great way to share meeting notes with your colleagues, or disseminate info to specific project teams.

We'll need to run a process to convert Portway documents to correctly formatted Slack messages. We've provided a small app to do this, which you can run on Heroku with a single click.

Create a Slack app

Create a Slack app to receive incoming webhooks. Follow Slack's instruction's here, and come back when you have a secret webhook URL (Step 3). Sending messages using Incoming Webhooks | Slack

Save this Slack webhook URL to use in the next step.

Spin up the portway-slack-webhook app

To make this as easy as possible, we've provided a "Deploy to Heroku" button in the repo.

Go to the Github portway-slack-webhook app and in the README, click the "Deploy to Heroku" button. You'll need to either create a new Heroku account, or use an existing one. There is no cost to run a hobby app on Heroku.

Alternatively, you may run the app anywhere, but it will need a publicly resolvable url.

Heroku Configuration

  1. Give the Heroku app a name. The name will be part of the URL.
  2. Heroku will ask you for a Config Var named sails_custom__slackIncomingWebhookURL. Enter the Slack webhook URL you created in the previous section, then click the Deploy app button!
  3. After the app has deployed, click the "Open app" button.
  4. Copy the URL shown. This will be our endpoint for the Portway webhook.

Add a webhook in the Portway project

  1. From Portway, navigate to your project and go to the project settings
  2. Choose "Webhooks" from the settings menu
  3. Add a new endpoint, which should be the Heroku app URL copied previously. It should look like https://app-name.herokuapp.com/api/v1/document/published where app-name is the name you chose for the Heroku app deployment.

Publish Portway Documents to Slack

At this point, any document you publish in your Portway project will now be posted to Slack. Share meeting notes, brainstorming sessions, and anything else.

You can have multiple Portway projects post to the same Slack channel by adding the Heroku endpoint to other Portway projects. You will need to run additional instances of the portway-slack-webhook app in order to post to different Slack channels however.

Heroku limitations

Heroku's free hobby-tier apps will go to sleep after a period of inactivity. Sometimes the app will not process the first request it receives when sleeping. This means if you publish a document in Portway, it might not show up in Slack. You can always navigate to the app's homepage to wake it up, then publish the document. Or publish the document again after a minute.