Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Troubleshooting Node.js Apps
      • Node.js Behavior in Heroku
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Building Add-ons
  • Add-on Development Tasks
  • Asynchronous Deprovisioning of Add-ons (Public Beta)

Asynchronous Deprovisioning of Add-ons (Public Beta)

English — 日本語に切り替える

Last updated August 07, 2023

Table of Contents

  • Example Workflow
  • Things to Know
  • Prerequisites
  • Implementation
  • Summary

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.

This feature is in public beta. To request access, open a support ticket.

Example Workflow

Async Deprovisioning Sequence Diagram

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.

For some resources, the Asynchronous Deprovisioning workflow isn’t appropriate. In that case, your service can respond with any other 2xx Successful response code besides 202 Accepted, and we immediately deprovision the add-on. Either a 204 No Content (preferred) or 200 Ok response works.

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.

Keep reading

  • Add-on Development Tasks

Feedback

Log in to submit feedback.

Writing to Application Logs as an Add-on Partner Asynchronous Provisioning of Add-ons

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices