Views: 6105
Last Modified: 22.08.2022

REST API interface allows to install your own server event handlers.

An events handler is an URL to which the system sends a request after a user performs an action on the Bitrix24 account, hosting the application.

The handler receives the following data on input:

  • event - specifies the event name.
  • data - an array containing the event data.
  • auth - contains the authentication information.

The handler can be:

  • using received authentication information to send requests to REST API.
  • be installed only by a user with account administrative rights.

Attention! If the event handler requires access to REST API to work with data, then it is strongly recommended to use the retrieved authentication data specifically, and not the data, saved on application side.

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.

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

List of available event can be found via the REST method events.

Event handler is installed as follows:

  • via REST method event.bind on the basis of restCommand:
    $handlerBackUrl  = '';
    $result = restCommand('event.bind', Array(
       'EVENT' => 'OnAppUpdate',
       'HANDLER' => $handlerBackUrl
    ), $_REQUEST["auth"]);
  • or via BX24.callBind JS-library function:
    BX24.callBind('OnAppUpdate', '');

    To get the list of registered event handlers, use REST method events.get.

    Removal of registered handler is done via REST method event.unbind or via JS-library function BX24.callUnbind.

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

    Application can install any number of handlers of the same event, but all handlers shall be installed with authentication of different users. Furthermore, ability to call a handler depends on the access permission of a user, whose authorization is used to activate a handler.

    event names are case-independent.

    Attention! When uninstalling or installing a new version of an application, all event handlers, installed by this application, will be deleted.

Courses developed by Bitrix24