Last updated August 07, 2023

The Asynchronous Deprovisioning feature allows add-on providers to act on an app where the add-on resource is attached before the provider’s access is removed by deprovisioning. Depending on the add-on provider, they can perform actions like shutting down one-off dynos or removing SSL certificates created by the add-on. You can also send follow-up communication to the customer, and so on.

Example Workflow

In the example, the add-on provider performs an ordered shutdown of their scheduler service by stopping all one-off dynos on the add-on. Then it sends relevant log messages to the application log before losing access to the customer application.

1. The customer requests to remove the add-on from the application by running the addons:destroy command through Heroku CLI.
2. We stop billing for the add-on resource and send an Async Allowed add-on deprovision request to the partner.
3. The partner responds to the deprovision request with a 202 Accepted response code.
4. The partner sends a request to the Dyno Stop endpoint for each of their controlled one-off dynos that are still running.
5. The partner sends a log message for each dyno stopped containing relevant information for the customer. The information includes the timestamp of when the dyno was killed, the command being executed, and the reason for killing it (add-on deprovisioning) using the log input URL linked with the add-on resource.
6. The partner makes an explicit call that tells Heroku that they’re done and don’t require further access to the Platform API on behalf of this resource.
7. We detach and remove the resource from the application, including the partner authorization. This step triggers an app restart.

See the Implementation section for the specifics of each part of this process.

Things to Know

Billing

Billing stops when the customer requests to deprovision the add-on. The time and cost of deprovisioning your service isn’t accounted for in how much a customer pays. Make sure to deprovision promptly so you don’t incur unnecessary costs.

Incomplete Add-on Deprovisionings

Add-ons that take longer than 12 hours to deprovision, or add-ons that your service fails to mark as deprovisioned via the API in that time period, are still considered deprovisioned. They are removed from customer apps and we don’t bill customers for provider delays in deprovisioning.

Prerequisites

• You must use the Platform API for Partners.
• To request access to this beta feature, open a support ticket.

Implementation

Determine if Async Deprovisioning is Allowed for a Resource

When we grant your add-on service access to Async Deprovisioning, all of our deprovision requests include an X-Async-Deprovision-Allowed header. It has a value of true or false.

Sometimes you can’t deprovision asynchronously. When an add-on is deprovisioned because the app is destroyed, the header is set to false and you receive the request after Heroku destroys both the add-on resource and the app. Any attempt to use the Platform API in this scenario results in 401 Unauthorized because of revoked and invalid access tokens.

An X-Async-Deprovision-Allowed header set to true indicates the customer requested to remove the add-on and you can deprovision asynchronously.

Respond to the Provision Request with a 202 Accepted

If your add-on service has access to the beta Asynchronous Deprovisioning feature and we send a deprovision request with the X-Async-Deprovision-Allowed header set to true, your add-on must:

1. Enqueue a job to deprovision the resource asynchronously.
2. Respond with a 202 Accepted response code.

This process tells Heroku to keep your add-on in a deprovisioning state, without removing your access tokens. You must explicitly mark the add-on as deprovisioned when you no longer require access to the Platform API.

Perform the Required Actions on the App

While the add-on is in a deprovisioning state, your access and refresh tokens are still valid to perform actions on the Platform API.

You must mark the add-on as deprovisioned as soon as you complete any pending actions over the customer’s app. We encourage you to access the Platform API to perform an ordered shutdown as soon as possible.

If your add-on service deprovisioning workflow requires time-consuming operations like database backups or infrastructure teardown, use background jobs to perform these actions after you mark the resource as deprovisioned. We don’t require providers to fully deprovision the resource on their side to mark the add-on deprovisioned.

Finish Add-on Deprovisioning

The final step is to tell Heroku that you deprovisioned the add-on and you don’t need further access to the Platform API. If this step isn’t taken within 12 hours of the deprovisioning request, we consider it completed and remove the add-on along with provider access. To indicate that deprovisioning has completed, use the Add-on Action Deprovision endpoint.

POST /addons/:uuid/actions/deprovision

At this point, the add-on and provider access and add-on config vars are removed. We create a new release and restart all application dynos.

Summary

Asynchronous Deprovisioning allows add-on partners to implement better and richer user experiences during deprovisioning. Providers must make a few changes to how they integrate with our APIs and have the feature enabled. Contact the Heroku Ecosystem Engineering team with any implementation-related questions.