Add-on Partner Event Notifications
Last updated 06 January 2020
This system is deprecated. Please use Webhooks instead.
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", ...]
}
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": "d.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": "d.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.