Last updated December 11, 2019

The Deploy Hooks add-on allows you to receive a notification whenever a new version of your app is pushed to Heroku. It’s useful to keep you and your team informed about deploys, while it can also be used to integrate different systems together.

After one or more hooks are set up, git push will show that they are scheduled to run:

$ git push heroku master
...

-----> Heroku receiving push
-----> Rails app detected
       Compiled slug size is 76K
-----> Launching...... done
-----> Deploy hooks scheduled, check output in your logs
       http://myapp.heroku.com deployed to Heroku

Hook output and errors appear in your application’s logs:

$ heroku logs
...
2011-03-15T15:07:29-07:00 heroku[deployhooks]: Sent email notification to me@example.com

Each deploy hook you need will be a new add-on instance. This allows you to pick and choose one or more that you want. Deploy hook types include IRC, Basecamp, Campfire, HipChat and a generic HTTP hook. Each type of deploy hook is represented as a different add-on plan. You can create and configure each deploy hook through the Heroku Dashboard or the Heroku CLI.

Dashboard

You can create the “Deploy Hooks” add-on on dashboard in the Resources tab. You can find specific instructions here.

Once you create the add-on, you can then configure it by navigating to the app in the Heroku Dashboard, going to the Resources tab and then clicking on the Deploy Hooks add-on you want to configure.

IRC

An IRC bot will connect to the specified server and message the room.

$ heroku addons:create deployhooks:irc \
    --server=irc.freenode.net \
    --room=devlounge \
    --nick=mydeploybot \
    --password=secret \
    --message="{{user}} deployed app"
Adding deployhooks:irc to myapp...Done.

Nick and password are optional. You can also set the server port by sending port=1234.

Basecamp

This hook will post a message to any Basecamp account you specify, under a certain project and post category (both specified by the name).

$ heroku addons:create deployhooks:basecamp \
    --url=http://myaccount.basecamphq.com \
    --username=00000000 \
    --project=myapp \
    --category=deploys \
    --title="{{user}} deployed myapp" \
    --body="check it at {{url}}"
Adding deployhooks:basecamp to myapp...Done.

NOTE: Please put your API Key under the username param above.

Campfire

Have any Campfire room receive an automated message when your app is pushed.

$ heroku addons:create deployhooks:campfire \
    --url=mycampfiresubdomain \
    --ssl=1 \
    --api_key=0000000 \
    --room=devlounge \
    --message="{{user}} deployed myapp"
Adding deployhooks:campfire to myapp...Done.

HipChat

This hook wil post a message to a HipChat room of your choice on app push. An authentication key is required for Heroku to access your HipChat account. To create one, fill out the form found in API Auth Tokens (available to group admins only). For maximum safety, set the type to “notification”.

To make Heroku send notices to a HipChat room on deploy, do the following:

$ heroku addons:create deployhooks:hipchat \
    --auth_token=my_auth_token \
    --room="My Company's Room" \
    --message="{{user}} deployed myapp"
Adding deployhooks:hipchat to myapp...Done.

Additional optional settings are:

• from: Name of the user sending the message (default: “Heroku”).
• notify: Boolean value (1 or 0) indicating whether the message should trigger a notification to users in the room (default: “1”).
• color: The background color of the message. (default: “purple”).
• message_format: Can be set to “text” for plain text messages, or “html” to support basic tags. (default: “html”).
• hipchat_api_url: API URL of HipChat server (in case of on-prem, non-hosted HipChat install). Example value is https://api.hipchat.com/v1/rooms/message. Details.

Check the HipChat API docs for more info on these options.

HTTP post hook

Performs an HTTP post to URL of your choice.

$ heroku addons:create deployhooks:http \
    --url=http://example.org
Adding deployhooks:http to myapp...Done.

The parameters are POSTed to your url with a mime type of application/x-www-form-urlencoded.

The parameters included in the request are the same as the variables available in the hook message: app, user, url, head, head_long, git_log and release. See below for their descriptions.

This is an example payload:

app=secure-woodland-9775&user=example%40example.com&url=http%3A%2F%2Fsecure-woodland-9775.herokuapp.com&head=4f20bdd&head_long=4f20bdd&prev_head=&git_log=%20%20*%20Michael%20Friis%3A%20add%20bar&release=v7

Email

This hook will send one or more emails. You can specify the subject and body, as follows:

$ heroku addons:create deployhooks:email \
    --recipient=me@example.com \
    --subject="Myapp Deployed" \
    --body="{{user}} deployed app"
Adding deployhooks:email to myapp...Done.

Email multiple recipients by adding additional email addresses separated by spaces.

Customizing messages

It’s possible to use variables when defining the message, title or subject of any deploy hook attribute.

For instance, use {{user}} when you want to see who deployed, and that text will be replaced for the actual user email whenever a hook is executed.

Available variables are:

• app: the app name
• user: email of the user deploying the app
• url: the app URL (e.g. http://myapp.heroku.com)
• head: short identifier of the latest commit (first seven bytes of the SHA1 git object name)
• head_long: identifier of the latest commit (SHA1 git object name)
• git_log: shortened log of commits between this deploy and the last (only supported when using the git deployment mechanism), or the description field for releases triggered via the Platform API
• release: identifier for the release (eg. v7)

Known issues and limitations

Deploy Hooks git_log not supported with Heroku Pipeline promotion, GitHub deploys, and Docker deploys

The git_log variable is only supported when using the git deployment mechanism.

With Pipeline promotion, GitHub automatic or manual deploys, and Docker deploys, DeployHooks does not have access to your git log and you will see a blank git_log variable. The git_log variable can only be set with a pure git deployment (e.g. git push heroku master).

Deploy Hooks do not work for deploys via the Container Registry.

For similar functionality consider App Webhooks.

Deploy Hooks does not fire for Review Apps when Deploy Hook is on the parent app

If you have a pipeline with Review Apps turned on, and there is a Deploy Hook configured for the parent app (either your staging or production app), new Review Apps will not fire a Deploy Hook on deploy. The configuration of add-ons is not copied to Review Apps.

Deploy Hooks only fire for releases

App releases (as documented in the Releases endpoint trigger Deploy Hooks, not app restarts, scaling, or config var changes. For more event types, consider App Webhooks.

Deploy Hooks has duplicated events for apps using Release Phase

We have observed duplicated Deploy Hooks events being sent for apps that make use of Release Phase. Consider App Webhooks instead of Deploy Hooks.

Alternatives to Deploy Hooks

An alternative to Deploy Hooks is to use App Webhooks instead. The Alerts and Notifications category on the Elements marketplace has several add-on solutions for providing notifications.