Webhooks are a more secure, reliable, and powerful alternative to Deploy Hooks, and five years ago, we made app webhooks Generally Available. Today, we are deprecating Deploy Hooks and encouraging customers to migrate to app webhooks.
Starting October 17, 2022, we will stop accepting new deploy hooks. Existing hooks will continue working until the product is sunset on February 17, 2023, but we encourage you to migrate your hooks as soon as possible.
There are many benefits to moving from Deploy Hooks to app webhooks, including:
App webhooks are more secure — You can verify that the messages you receive were made by Heroku and that the information contained in them was not modified by anyone. Refer to the Securing webhook requests section of the official documentation for more information on how to achieve this.
With webhooks, you are in control of the notifications! — If you subscribed at the sync notification level, Heroku retries failed requests until they succeed or until the retry count is exhausted. Additionally, each notification has a status that you can check to monitor the current health of notification deliveries.
More than 20 events are currently supported by app webhooks — This includes release events. You can be notified every time a Heroku Add-on is created, when a build starts, or when the formation changes, among many other things. See the webhook events article for example HTTP request bodies for all event types.
Below you will find a quick migration guide and some differences to note between the two alternatives.
Steps to migrate from HTTP post hooks to webhooks
List your current add-ons.
heroku addons --allFor each deploy hook with the HTTP plan, open the Add-on page.
heroku addons:open <add-on name>
You will be presented with a page like this:
Copy the URL shown on the Add-on page.
Create a webhook using the URL.
heroku webhooks:add -i api:release -l notify -u <URL> -a <your app name>Verify your webhook (you can use the releases:retry plugin to trigger a release).
heroku releases:retry -a <your app name>Remove the deploy hook.
heroku addons:destroy -a <your app name> <your add-on name>
App webhooks only support calling an HTTP(S) endpoint, so if you have deploy hooks using email or IRC plans, you will need to build an intermediate app to receive the webhook and send an email or post an IRC message.
Keep in mind that webhooks do not support adding dynamic parameters, such as revision={{head}}, to the webhook URL. If your HTTP post hook made use of this feature, you will need to build an app to receive the webhook, extract the needed values from the payload, and call your URL passing the parameters you need.
Another difference between app webhooks and Deploy Hooks is that you will receive a message when the deploy starts and a follow up message when it is finished. You may receive a third message if you have a release phase command. Please read this KB article for more info about this behavior.
Lastly, you should consider the differences on the payload sent by Deploy Hooks and webhooks, and update your receivers accordingly.
To ease this transition, we have made an app that handles most of these differences, and you can check it out on GitHub.
To learn more, please see the app webhooks article or try the app webhooks tutorial.
If you have any questions or concerns about this transition, please feel free to reach out to us.
Happy coding!