This add-on is operated by Crazy Ant Labs

Keep your team notified when your Heroku app is deployed, released or updated

Last updated January 26, 2024

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. You can use filtering conditions to eliminate the ones you don’t want trigger notifications for.
• 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.

Filtering rules

You can apply filtering rules to trigger notifications that meet specified criteria, i.e. have (or don’t have) certain properties.

With filtering rules, you can specify conditions that must be met for Activity To Go to trigger notifications. This allows you to create customized rules for triggering subscriptions, based on specific criteria.

Subscription filters use the AND operator to combine filtering rules. This means that all specified conditions must be met in order for the subscription to be triggered. Each rule consists of three elements: field, operator, and value.

Fields

The following fields can be used in a filtering rule:

• Action: The event type that triggered the event. This can be create, update or destroy.
• Actor ID: The identifier of the actor - the Heroku user that initiated the action that triggered the event.
• Actor Email: The email of the actor - the Heroku user that initiated the action that triggered the event.
• App ID: The identifier of the Heroku application that the event took place on.
• App name: The name of the Heroku application that the event took place on.
• Current: For release events, this indicates whether the release has been promoted to the current release.
• Description: The value of the description field in the event data.
• Status: The value of the status field in the event data.
• Previous status: The value of the status field in the previous event data.

Operators

The following operators can be used in a webhook filter:

• Is: Checks if the field and value match exactly (e.g. Actor Type Is User).
• Is not: Checks if the field and value don’t match (e.g. Actor Type Is not IAM).
• Contains: Checks if the field contains the value (e.g. Path Contains user).
• Doesn’t contain: Checks if the field does not contain the value (e.g. Path Doesn’t contain user).
• Starts with: Checks if the field starts with the value (e.g. Path Starts with /user).
• Ends with: Checks if the field ends with the value (e.g. Path Ends with mary).
• Matches: Checks if the field matches the regular expression in the value (e.g. Path Matches (mila|mary|greg)).

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. Transformation - change from None (default) to Heroku deploy hooks if you’re migrating integrations done using Heroku Deploy Hooks.
3. Content type - change from application/json (default) to x-www-form-urlencoded if you’re migrating integrations done using Heroku Deploy Hooks.
4. 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.
5. 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 from Heroku Deploy Hooks

Heroku Deploy Hooks was sunset on February 17, 2023. To keep your integrations working, you can replace Deploy Hooks with Activity To Go:

1. Provision Activity To Go in your app (or attach an existing add-on to another app).
2. Create a subscription for build or release events and add a webhook action.
3. Copy the endpoint URL you use with Deploy Hooks.
4. Select Heroku deploy hooks transformation and x-www-form-urlencoded content type for the endpoint, so Activity To Go webhooks payload will be equivalent to Deploy Hooks’ webhooks payload.

Keep in mind that several actions may trigger a release, you will receive a notification for every release. This is slightly different from what you received with Deploy Hooks; if you only want to receive a notification when a code change happened you need to [filter messages][#filtering-rules] based on the description. Code changes have a description starting with Deploy.

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.

Questions and Answers

Q: Do I need to install Activity To Go on each of my Heroku apps?

A: No. You can attach a single Activity To Go add-on to multiple apps and stream the activity from all of them to different subscriptions.

Q: Why can’t I see the git commit message in my Activity To Go updates?

A: The git message is only supported when using the git deployment mechanism. With other types of deployments (e.g. Heroku Pipelines, Docker deploys) the message is inaccessible.

Q: I get duplicate messages when using the release phase. Why?

A: The Heroku webhooks trigger multiple times per release. For more information, see here. You can use filters to eliminate certain notifications with the release topic.

If you’re using the release phase, the following filters will cause the action to be triggered only on once (either a failure, or the success of the 2nd event):

Status is not pending and Action is update and Current is false

If you’re not using the release phase, the following filter will cause the action to be triggered only once:

Status matches failed|succeeded

Other filters you may use:

• Action contains update - eliminate the first event
• Status does not contain pending - eliminate the first event
• Status contains failed - triggers only when release fails
• Status matches succeeded|failed and Action contains update - triggers only on success/failure and not on the first (create action) event

If you only want to receive a notification when a code change triggered the release, you need to add a rule to filter Description. Code changes have a description starting with Deploy:

• Description starts with Deploy - triggers only when a code change triggered the release

Q: Does Activity To Go work with Sentry?

A: Yes. To migrate your Heroku Deploy Hooks integration with Sentry, follow the instructions here.

Q: Does Activity To Go work with Bugsnag?

A: Yes. To migrate your Heroku Deploy Hooks integration with Bugsnag, follow the instructions here.

Q: Does Activity To Go work with Rollbar?

A: Yes. To migrate your Heroku Deploy Hooks integration with Rollbar, follow the instructions here.

Q: Does Activity To Go work with Microsoft Teams?

A: Yes. To get notified on Microsoft Teams, follow these steps:

1. Add an incoming webhook URL in to you Microsoft Teams (follow the procedure here.
2. Add an Activity To Go subscription with the events you’d like to trigger notifications and select the webhook action.
3. Copy your incoming webhook URL to the action’s endpoint URL.
4. Change the transformation to Microsoft Teams.
5. Select content type application/json.
6. Click done. That’s it!