Activity To Go

This add-on is operated by Crazy Ant Labs

Keep your team notified on all Heroku app changes in Slack

Activity To Go

Last updated 14 June 2020

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:

A list of all plans available can be found here.

$ 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:addon-attachment : create, destroy
  • api:addon : create, destroy, update
  • api:app : create, destroy, update
  • api:build : create, update
  • api:collaborator : create, destroy, update
  • api:domain : create, destroy
  • api:formation : destroy, update
  • api:sni-endpoint : create, destroy, update
  • api:ssl-endpoint : create, destroy, update

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.

Activity To Go can only post messages to your Slack channels. It won’t ask for permissions to read any of your data.

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.

Please note that our webhooks don’t work with self-signed certs. If a webhook detects a self-signed cert, it will throw an error and no request will be sent.

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

If you do not return a 200-level status code, Activity To Go records the failure. You can view the failure in the activity feed.

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

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

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:

This will destroy all associated data and cannot be undone!

$ 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.

Feedback

Log in to submit feedback.