/heroku-discord-bridge

A simple Discord webhook for Heroku

Primary LanguageJavaScript

Heroku-Discord Bridge

sample-message

Overview

This application serves as a webhook that posts a message in a specified Discord channel whenever certain actions are executed in Heroku (e.g., build initiated, application deployed, etc.). Essentially, it is middleman between a Discord bot and a Heroku webhook. It's built using Koa, a lightweight framework for Node.js.

Currently, it only supports notifications in a single Discord channel.

Set Up Discord Application

Create Application

  1. Navigate to the Discord Developer Portal.
  2. Select the New Application button. Enter a unique name, then select the Create button.

Add Application to Discord Server

  1. Once you create an application on the Discord Developer Portal, obtain the Application ID from the General Information page.
  2. Using a web browser, navigate to https://discord.com/api/oauth2/authorize?scope=bot&permissions=536870912&client_id=<APPLICATION_ID>
  3. Select the server where the notifications should be posted, then select the Continue button.
  4. Ensure the Manage Webhooks option is selected on the subsequent screen, then select the Authorize button.

Environment Variables

Create .env file containing the following variables:

DISCORD_BOT_NAME

(Optional) Specify a name for the bot sending the message. If not specified, defaults to "Heroku Notifier"

DISCORD_MESSAGE_CONTENT

(Optional) Specify a static message to use. If not specified, defaults to "APP build STATUS initiated by EMAIL"

DISCORD_BOT_TOKEN

The Discord bot's token

  1. Navigate Discord Developer Portal.
  2. Select the application under My Applications.
  3. Select Bot from the sidebar.
  4. Select the Add Bot button. Then select the Yes, do it! button.
  5. Under Build-A-Bot, under Token, select the Copy button.

DISCORD_CHANNEL_ID

The ID of the Discord channel in which to post the messages. Can be found by referencing the channel's URL using the browser-based version of Discord.

HEROKU_SECRET

This key is used by Heroku to sign requests and is generated by Heroku when a webhook is created. See the Heroku Documentation for more details. The bridge will check all requests using this shared secret.

  1. In the Heroku dashboard, open the app for which to receive messages.
  2. Select More -> View webhooks.
  3. Select the Create Webhook button.
  4. Enter:
    • Webhook Name (optional): How the webhook will be referenced in the control panel
    • Payload URL (https): The URL where the bridge is hosted
    • Secret (optional): A random string that will be used to sign requests; automatically generated if not specified
  5. Select the Event Types to subscribe. Then select the Add Webhook button.
  6. The secret will be displayed on the subsequent screen. (Note that this will be the only time it will be displayed.)

Only one secret is supported, so if you would like to receive messages for multiple Heroku applications, you can specify the same secret when creating the webhook for each application.

Deployment

npm run build
npm run start