This add-on is operated by Crazy Ant Labs

Keep your team notified when your Heroku app changes via Slack or Webhook

Last updated September 07, 2022

Activity To Go allows you to receive notifications whenever a change occur in your Heroku app. It keeps you and your team informed and also allows you to integrate change notifications to other systems.

After one or more subscriptions are setup, you will be automatically notified on changes to your app.

Provisioning the add-on

Activity To Go can be attached to a Heroku application via the CLI:

$ heroku addons:create activitytogo
-----> Adding activitytogo to sharp-mountain-4005... done, v18 (free)

You can attach your Activity To Go add-on to another app:

$ heroku addons:attach activitytogo-tapered-77105 -a sushi
-----> Attaching activitytogo-tapered-77105 to sushi.. done, v18 (free)

After you provision Activity To Go, go to the dashboard (see below) to configure the integrations and events to notify on.

Dashboard

The Activity To Go dashboard allows you to set up event subscriptions.

You can access the dashboard via the CLI:

$ heroku addons:open activitytogo
Opening activitytogo for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select Activity To Go from the Add-ons menu.

To create a new subscription, click the Add subscription button and follow the instructions. You can also edit or duplicate an existing subscription, pause, resume or delete a subscription.

After you create a subscription you can also view the latest events for it on the dashboard.

Subscriptions

Subscriptions define the types of notifications you’d like to be informed about - Topics - and the Actions you’d like to take when notifications are triggered.

When creating or editing a subscription:

1. Define a nickname to identify the subscription by (optional).
2. Select one or more topics (see below).
3. Select an action to take (see below).

Topics

The following is a list of event types that Activity To Go can can notify you on in case of changes in your apps:

• api:release: create,update. This is triggered whenever a new release for the app has been initiated or the release’s status has changed since the last notification. Note that if your application is using release phase you will receive 3 events per release: create, update, update.
• api:app : create, destroy, update. Triggered when the app is created, destroyed or its details have been modified.
• api:build : create, update. Triggered whenever a new build has been initiated or the build’s status has changed since the last notification.
• api:collaborator : create, destroy, update. Triggered when collaborators are added or removed from the app, or an existing collaborator’s details have been modified.
• api:domain : create, destroy. Triggered when custom domain details have been added or removed from the app.
• api:formation : destroy, update. Triggered when the dyno formation for a particular process type has been modified.
• api:sni-endpoint : create, destroy, update. Triggered when an SNI endpoint has been specified or removed for the app, or when an existing SNI endpoint’s details have been modified.

See here for more information on specific event types.

Actions

Activity To Go allows you to use one action per subscription. The available actions are:

• Send a Slack message
• Send a Webhook request
• Run a one-off dyno
• Stream to Amazon S3

Slack action

Slack messages are great to keep your team up to date on what’s going on in your Heroku apps.

To configure the Slack message action, you will be required to create a one-way webhook in Slack in order to allow Activity To Go to post messages to a specific person or channel in your Slack workspace. Once you authorize Activity To Go to post messages, you can create the subscription and receive notifications to your Slack workspace.

Webhook action

Activity To Go can send a webhook notification for each notification received from Heroku. Webhook notifications are sent as HTTPS POST requests to a URL of your choosing. To integrate with webhooks, you need to implement a server endpoint that receives and handles these requests.

To configure the Webhook S3 request action, fill out the following:

1. Endpoint URL - HTTPS URL of your server endpoint that will receive all webhook notifications.
2. Signing Secret (optional) - if specified, this will be used to sign each request in the X-Hub-Signature header. You can use the X-Hub-Signature header to verify the authenticity of the request.
3. Authorization Header (optional) - a custom Authorization header that will be included with all webhook notifications.

Receiving Webhooks

When a webhook event that you’ve subscribed to occurs, Activity To Go sends a POST request to your server endpoint with the details of the event.

You can verify the authenticity of these requests in the following ways:

• The request’s Authorization header matches the value you provided when subscribing to notifications.
• The request’s X-Hub-Signature header contains the HMAC SHA256 signature of the request body (signed with the secret value provided when subscribing).

A resulting webhook notification request resembles the following:

POST https://webhook.site/394f2074-e56f-4110-7bf7-ca14a1f48b7c
Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef
X-Hub-Signature: cLcN5U5x+jHEkANnVaaRwBw7yE4uv4pXdjcY9Cajc7M=

{
  "metadata": {
    "subscription": {
      "id": "6cede787-5c17-4882-817c-1afb4a138888"
    },
    "delivery": {
      "Id": "f98d5318-76dd-4527-9ed0-5bb05d6420b4"
    },
    "attempt": {
      "id": "c94c2417-a9df-4ab3-a10c-43b8d78c8885"
    },
    "event": {
      "id": "bbebd62d-3998-46bc-98da-43bd13be971d",
      "topic": "ping"
    }
  },
  "actor": {
    "id": "12011f29-3487-424c-a7c5-c73251ec13b4",
    "email": "bruce@wayne-enterprises.com"
  },
  "data": {
    "web_url": "https://api.activitytogo.com/organizations/c4099fcd-582b-4302-b3de-51108d5b6449/dashboard",
    "name": "Webhook Notifications",
    "id": "6cede787-5217-4882-811c-1aeb4a138888"
  },
  "updated_at": "2020-05-31T09:35:49.641Z",
  "resource": "ping",
  "previous_data": {},
  "action": "create",
  "created_at": "2020-05-31T09:35:49.641Z",
  "id": "bbebd62d-3998-46bc-98da-43bd13be971d"
}

You should always respond with a 200-level status code to indicate that you received the notification. Activity To Go ignores the body of your response, so a 204 status with an empty body is ideal:

204 No Content

Webhook event formats

The payload consists of the webhook events as described here, and each event is augmented with metadata that helps track the event in Activity To Go. For example:

{
  "metadata": {
    "subscription": {
      "id": "6cede787-5c17-4882-817c-1afb4a138888"
    },
    "delivery": {
      "Id": "f98d5318-76dd-4527-9ed0-5bb05d6420b4"
    },
    "attempt": {
      "id": "c94c2417-a9df-4ab3-a10c-43b8d78c8885"
    },
    "event": {
      "id": "bbebd62d-3998-46bc-98da-43bd13be971d",
      "topic": "ping"
    }
}

One-off dyno action

Activity To Go can run a one-off dyno in your source app or any target app it is attached to when notifications are triggered to let you respond to such events programmatically, without having a server continuously listen for webhooks.

To configure the one-off dyno action, fill out the following:

1. Command - the command or process type to run.
2. Application (optional) - the target application in which the one-off dyno starts. If left blank, the one-off dyno will be started in the app that is associated with the event, in case you attached the add-on to multiple applications.
3. Dyno size - The size of the one-off dyno. Each dyno type incurs a different cost and has different resources and limits.
4. Timeout - The number of seconds until the one-off dyno expires, after which it will soon be killed. Read more here.

When your one-off dyno executes, it has access to the following environment variables that contain the event data:

• ACTIVITYTOGO_EVENT_TOPIC
• ACTIVITYTOGO_EVENT_RESOURCE
• ACTIVITYTOGO_EVENT_ACTION
• ACTIVITYTOGO_EVENT_PAYLOAD - json payload

Amazon S3 action

Activity To Go can also stream events to files in your Amazon S3 bucket, so that you can store this information for security compliance purposes, further analysis or integration with other 3rd party tools.

To configure the Amazon S3 action:

1. Create an Amazon S3 bucket in your preferred region.
2. Configure the Amazon S3 action: copy the bucket name, select the bucket region and whether or not server-side encryption is required.
3. Click the Generate bucket policy button to copy the generated bucket policy to the dashboard.
4. Edit your bucket policy in the AWS Console and paste the generated policy to allow Activity To Go to stream data into the bucket. If a bucket policy already exists, you will have to merge our policy with your current one.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade activitytogo:newplan
-----> Upgrading activitytogo:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: activitytogo:newplan

Removing the add-on

You can remove Activity To Go via the CLI:

$ heroku addons:destroy activitytogo
-----> Removing activitytogo from sharp-mountain-4005... done, v20 (free)

Support

All Activity To Go support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at hello@crazyantlabs.com.