Installing your app

Before using any of your app features, an account admin need to first install the app to their account. This applies to both marketplace apps and private apps for a specific account.

Install and Uninstall Webhook URL

You can use the endpoint present in the "Webhooks" section of your app's configuration screen to get notified when someone installs or uninstalls your app. This is useful for tracking how many installs your app has, or for managing subscriptions and external webhooks.

When your app is installed, your endpoint will receive a POST request from the monday apps server with a JSON object about the installation event. You can use this to kick off some application logic, such as counting how many installs your app has, starting a trial period for the customer, and more.

When the app is uninstalled, your endpoint will receive a similar POST request, with a different event in it, stating that someone uninstalled your app.

Samples of the install and uninstall event payloads are below. Timestamps are in UTC.

{
  "type":"install",
  "data":{
    "app_id":1000000000,
    "user_id":3,
    "user_email":"[email protected]",
    "account_id":1,
    "version_data":{
      "major":1,
      "minor":2,
      "patch":0,
      "type":"minor",
      "user_name": "John Doe",
      "account_tier": "standard",
      "account_max_users": 20,
      "user_cluster": "ngo",
    },
    "timestamp":"2022-06-28T06:48:06.643+00:00",
    "subscription":{
      "plan_id":"plan2",
      "renewal_date":"2022-07-19T00:00:00+00:00",
      "is_trial":false,
      "billing_period":"monthly",
      "days_left":21
    }
  }
}

{
  "type":"uninstall",
  "data":{
    "app_id":1000000000,
    "user_id":3,
    "user_email":"[email protected]",
    "account_id":1,
    "version_data":{
      "major":1,
      "minor":2,
      "patch":0,
      "type":"minor",
      "user_name": "John Doe",
      "account_tier": "standard",
      "account_max_users": 20,
      "user_cluster": "ngo",
    },
    "timestamp":"2022-06-28T06:48:06.643+00:00",
    "subscription":{
      "plan_id":"plan2",
      "renewal_date":"2022-07-19T00:00:00+00:00",
      "is_trial":false,
      "billing_period":"monthly",
      "days_left":21
    }
  }
}

For an explanation of the different IDs in the payload, check out this table: Multitenancy Best Practices

When the account is in a trial tier, the account_tier field will come back as null.

You can add your endpoint by going to your "Webhooks" section under the "Manage" area of the left side panel.

How do I install an app on my own account?

You can install your app on your own account directly from the Developers' section of your account. This is useful if you're building an app and want others on your account to use its features on their boards.

In the leftpane of the main app page, you will see an Install tab. Click this to see an option to install your app.

How do my users install my app on their account?

Others can install your app directly on their account if you publish it and share the installation link with them. For a full walkthrough on how to do this, check out this article: Sharing Your Apps with Customers

If your app is listed in the monday apps marketplace, any monday.com user can install your app. For a full walkthrough of the marketplace install process, check out this article: monday apps marketplace

📘

Do you have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Don’t forget to search before opening a new topic!