Events

REST interface allows setting up your own handlers for server events.

Handler is a URL that is called after user performs requested action at the Bitrix24 account with installed application. Because queries are sent from Bitrix24 servers, any URL will must be available for external GET/POST.

Handler receives the input data as follows:

Query field	Description
event	Triggered event name
data	Array with event data. Depends in event.
auth	Sets of authorization data.

The handler can perform the following actions:

• use the retrieved auth data for executing queries to REST API.
• be assigned only to user having administrative access permissions for account.

Note.When event handler requires a query to REST API for handling data, it's strongly recommended to use the auth data, saved in the application, instead of getting access_token, because it may be unavailable.

You need to indicate the user for event handler authorization. By default, event handler is issued with authorization for the user who's actions had triggered the events.

Event handler won't be called immediately but after some time depending on the load, after triggering the event.

You can retrieve the list of available events using the REST method events.

Use the REST method event.bind or JS library function BX24.callBind to assign an event handler. You can get registered event handlers via REST method events.get

Removing a registered event handler is performed via the REST method event.unbind or using JS library function BX24.callUnbind.

You must request a corresponding access permission to access each event when registering an app version.

Application can set an arbitrary number of handlers for a single event, but all handlers must be assigned with authorization for different users. Additionally, event handler call can depend on user access, which authorization will be issued to the handler.

Event names are case insensitive.

Attention! Registered default handlers are saved during app version upgrades. If required, they can be deleted by the installation handler for a new app version.

Example

App installation event

array(
  'event' => 'ONAPPINSTALL',
  'data' => array(
    'VERSION' => '1',
    'LANGUAGE_ID' => 'en',
  ),
  'ts' => '1466439714',
  'auth' => array(
    'access_token' => 's6p6eclrvim6da22ft9ch94ekreb52lv',
    'expires_in' => '3600',
    'scope' => 'entity,im',
    'domain' => 'portal.bitrix24.com',
    'server_endpoint' => 'https://oauth.bitrix.info/rest/',
    'status' => 'F',
    'client_endpoint' => 'https://portal.bitrix24.com/rest/',
    'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
    'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8',
    'application_token' => '51856fefc120afa4b628cc82d3935cce',
  ),
)