Add-on Partner Event Notifications

Last updated 25 May 2017

As an Add-on Partner, you can opt-in to receiving certain event notifications that happen on apps where your add-on is installed. This document outlines the different types of events, how to opt-in to them and what you can expect from each one.

Opting in to an event notification

You may opt-in to any event notification by adding it to the requires array in your manifest. For example, if you wanted to subscribe to Deployment Notifications, you would update your manifest to reflect:

{
  "requires": ["deploy_notify", ...]
}

This system is temporary. It will eventually be replaced by a full-fledged webhook solution that sits on top of an incredibly robust messaging system. It will exposed via the Public API which we intend give partners access to. For the time being, however, the current notification system is outlined here-within.

Request structure

When an notification is triggered it will send an event to the following URI:

POST /heroku/resources/:id/events

This endpoint should act just as the others in your provision API do. id is the ID you’ve sent back to Heroku when we provisioned the add-on. The request body will be in the format of:

{
  "heroku_id": "<app heroku id>",
  "event": "<event type>",
  "detail": {
    <event specific data>
  }
}

Event types

Deployment notifications

Deployment notifications get triggered when a user redeploys their app.

Requires Flag

deploy_notify

Request payload

{
  "heroku_id": "app123@heroku.com",
  "event": "deploy",
  "detail": {
    "app": "deploying-furiously-42",
    "user": "jane@somedomain.com",
    "url": "http://deploying-furiously-42.herokuapp.com",
    "head": "441e20",
    "head_long": "441e204ea9f2ddeb4fcdd7f641e6c7240ffb8b91",
    "prev_head": "953fd37b50c1382a9b7364364791e9be7e6efc71",
    "git_log": "441e204 Merge pull request #1253 from janedoe/make-it-rain
b980268 Awesome new feature
953fd37 Merge pull request #1248 from janedoe/quick-bug-fix
eb9d86d Missing something simple
4c15970 Merge pull request #1249 from janedoe/better-commit-messages-required"
  }
}

Attachment notifications

Attachment notifications occur when a user attaches your add-on to an app. This can be when attaching to the same app (in the case of many_per_app) or to another app (in the case of attachable).

For more information about how to make your add-on attachable, checkout the article Making Your Add-on Shareable.

Requires flag

attach_notify

Request payload

When an attachment is added

{
  "heroku_id": "app123@heroku.com",
  "event": "attach",
  "detail": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "MYADDON_CYAN",
    "log_token": "01234567-89ab-cdef-0123-456789abcdef",
    "resource": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "writing-nobly-1234"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  }
}

When an attachment is removed

{
  "heroku_id": "app123@heroku.com",
  "event": "detach",
  "detail": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "MYADDON_CYAN",
    "log_token": "01234567-89ab-cdef-0123-456789abcdef",
    "resource": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "writing-nobly-1234"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  }
}

log_token is optional and is only available to specific partners. If you feel your add-on would require log access, contact our Partner Team. The following links offer more information about integrating with Heroku’s Logplex system:

Response

Your service should respond with a 200 status code to acknowledge you received the notification. We will retry the request a few times if we do not receive a successful response.

Feedback

Log in to submit feedback.