Event After Successful Application Installation onAppInstall

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: basic

Who can subscribe: any user

The ONAPPINSTALL event is triggered immediately after the successful installation of an application on Bitrix24. An application without an interface also receives the event when it is updated.

Events will not be sent to the application until the installation is complete. Check the application installation.

What the Handler Receives

Data is transmitted as a POST request

{
            "event": "ONAPPINSTALL",
            "event_handler_id": "11",
            "data": {
                "VERSION": "1",
                "ACTIVE": "Y",
                "INSTALLED": "Y",
                "LANGUAGE_ID": "de"
            },
            "ts": "1696527000",
            "auth": {
                "domain": "some-domain.bitrix24.com",
                "scope": "crm,user",
                "access_token": "s6p6eclrvim6da22ft9ch94ekreb52lv",
                "refresh_token": "4s386p3q0tr8dy89xvmt96234v3dljg8",
                "expires_in": "3600",
                "server_endpoint": "https://oauth.bitrix.info/rest/",
                "status": "F",
                "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                "member_id": "a223c6b3710f85df22e9377d6c4f7553",
                "application_token": "51856fefc120afa4b628cc82d3935cce"
            }
        }

Request Parameters

Required parameters are marked with *

Name
type

Description

event*
string

Symbolic event code. In this case — ONAPPINSTALL

event_handler_id
integer

Event handler ID

data*
object

Data about the installed application.

The structure is described below

ts*
timestamp

Date and time of the event sent from the queue

auth*
object

Object containing authorization parameters and information about the account where the event occurred.

The structure is described below

Parameter data

Name
type

Description

VERSION*
string

Number of the installed application version, for example 1

ACTIVE*
string

Application activity status. Always Y: events are not sent to inactive applications

INSTALLED*
string

Whether the application is ready for use. Always Y: events are not sent until the installation is complete

LANGUAGE_ID*
string

Default language of the Bitrix24 account: ru, en and others

Parameter auth

Name
type

Description

domain*
string

Address of the Bitrix24 account where the event occurred

scope
string

Codes of the permissions granted to the application, separated by commas

access_token
string

OAuth 2.0 authorization token

refresh_token
string

Token for extending OAuth 2.0 authorization

expires_in
integer

Access token lifetime in seconds

server_endpoint*
string

Authorization server address for token renewal

status
string

Status of the application that subscribed to this event:

  • L — local application
  • F — free mass-market application
  • D — demo version of a mass-market application
  • T — trial version of a mass-market application, time-limited
  • P — paid mass-market application

client_endpoint*
string

Common path for API method calls to the account

member_id*
string

Unique identifier of the account

application_token*
string

Application token. Retain it: handlers of other events use it to verify that the request came from Bitrix24. For more details, see the article Security in Handlers

If the event could be linked to a user, auth contains access_token, refresh_token, expires_in, scope, and status, more details.

If the application has no interface and an installation URL is specified, Bitrix24 automatically registers the ONAPPINSTALL handler on this URL during installation.

You can set a handler on a different URL with the event.bind method in the installation script of the application. The script URL is specified in a separate field of the application version card.

Continue Learning

Previous
Overview of Events
Next
When Creating an Application System User