Handling Events

REST API inferface allows developer to specify handlers for server events.

Event handler is a URL to which the system sends a query after a user performs a requested action on the Intranet hosting the application. Because queries will be sent from Bitrix24 servers, any URL must be accessible for external GET/POST queries.

The handler receives the following data on input.

The handler:

• can use the received authentication information to send requests to REST API;
• can be installed only by a user having administrative privileges.

Note: when an event hander needs to query REST API to handle data, it's strongly recommended to use the passed authorization data specifically for this purpose instead of the data saved on the side of the app.

When installing a handler, the application can specify a user, whose credentials will be used by the event handler for authentication. By default, the event handler will be authenticated as a user whose actions triggered the event.

Notice: event handler is not called immediately after an event had occurred. It will be activated after some time which depends on a current server load.

To get a list of available events, use the REST method: events.

To install an event handler, use the event.bind method, or the JS library function: BX24.callBind.

To uninstall a previously set event handler, use the event.unbind method, or the JS library function: BX24.callUnbind.

To enable an application to access a specific event, a corresponding access permission has to be requested when registering an application version.

An application can install as many handlers for the same event as needed, provided that each of these handlers is installed for a different user. Furthermore, a handler may or may not be called which depends on the access permission of a user whose authorization is used to activate a handler.

The event names are case-insensitive.

Attention! When uninstalling an application or registering a new version, all the previous handlers are deleted.

Example

Application 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://accountname.bitrix24.com/rest/',
    'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
    'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8',
    'application_token' => '51856fefc120afa4b628cc82d3935cce',
  ),
)

All REST Events