Last updated April 08, 2025

Dyno events expose the full lifecycle of events for dynos in a Heroku app. Dyno events let you gain insight into:

• When dynos are created in response to formation changes
• When one-off dynos are created
• When dynos are scaled in response to an autoscaling event
• When dynos are involved in an app restart

These events are available as webhook notifications you can subscribe to. See the App Webhooks article, as well as the demo tutorial, for information on how to set up app webhooks.

Subscribing to dyno event notifications

Subscribe to webhook notifications for dyno events with the following command:

$ heroku webhooks:add -i dyno -l notify -u https://example.com/hooks
Adding webhook to ⬢ app ... done
=== Webhooks Signing Secret
475beb0bf7de962fb89878a767c22f7de22154dae1e6996b6b33299e7a0f

Testing notifications

You can easily check whether you’re successfully receiving dyno event notifications by doing any of the following:

• Scale your app’s number of dynos up or down.
• Restart an app with at least one running dyno.
• Create a new one-off dyno with the heroku run command.

Dyno event format

Dyno event request bodies have the following format, which closely mimics the dyno endpoint of the Platform API:

{
  "id": "cb6efa95-32a3-46af-8275-cb1350f684c2",
  "data": {
    "id": "6b8f4aa5-f329-44a1-bbab-09421ecc7b68",
    "app": {
      "id": "8e8f7f7e-bc0d-41db-a3c1-4d8a49719e47",
      "name": "secret-dawn-52107"
    },
    "name": "run.9359",
    "size": "Eco",
    "state": "starting",
    "command": "bash",
    "release": {
      "id": "b2e4ed3e-fce4-4df5-93ab-829b49ad6435",
      "version": 5
    },
    "management": "run:attached",
    "exit_status": null
  },
  "created_at": "2017-10-18T20:13:23Z",
  "webhook_metadata": {
    "event": {
      "id": "cb6efa95-32a3-46af-8275-cb1350f684c2",
      "include": "dyno"
    },
    "attempt": {
      "id": "501cf85e-dcfd-4bef-9272-c87f4b86fe9a"
    },
    "webhook": {
      "id": "457e230a-4ed0-4840-8863-3b8c635c0128"
    },
    "delivery": {
      "id": "d6767a62-4cef-4c46-ab81-6a6e15e28353"
    }
  }
}

There are two attributes available in the request body that are not provided by the dyno endpoint:

• The exit_status attribute provides the exit status of the command the event is related to.
• The management attribute indicates the method by which the dyno was created, which is one of the following:
  • run:detached
  • formation
  • run:attached

Dyno Event States

Dynos report events with the following states:

• starting - Dyno is starting.
• stopping - Dyno is stopping.
• up - Dyno is up and running.
• down - Dyno is down. The event contains the exit status of the dyno at exit_status.
• crashed - Dyno has crashed. The event contains the exit status of the dyno at exit_status.
• unknown - Dyno is in an unknown state. This state is not commonly encountered.

Cedar

For Cedar-generation dynos, the normal lifecycle proceeds from starting -> up -> stopping.

A dyno that starts successfully and then eventually crashes goes through starting -> up -> crashed.

Fir

For Fir-generation dynos, the normal lifecycle proceeds from starting -> up -> stopping -> down.

A dyno that starts successfully and then eventually crashes goes through starting -> up -> crashed -> down.

Known issues

The following are known issues with webhook dyno events during this public beta.

One-off dynos

• For Common Runtime dynos, one-off dynos created via heroku run always have a final state of down (in the case of timeout), or crashed, even if the command exits successfully. Always check the exit_status attribute of the notification request body to determine whether the command was in fact successful.

• The exit_status of dyno events for expired one-off dynos differs between the Common Runtime and Private Spaces. This is caused by differences in the way the two runtimes terminate one-off dynos that have exceeded their time_to_live.

  • Common Runtime dynos will have an exit_status of 143 (SIGTERM)
  • Private Spaces dynos will have an exit_status of 0

Duplicate dyno events

• For Cedar Private Spaces dynos, web hooks may receive duplicate dyno events for the dyno states up and complete.