Views: 3746
Last Modified: 26.01.2021

  Description

Webhooks feature allows using Bitrix24 UI to retrieve authentication keys to be employed by an application for calling REST methods; unlike OAuth 2.0 tokens, such keys have infinite lifetime.

This makes webhooks an exceptionally attractive means of communication with the Bitrix24 system over REST. However, this approach have some disadvantages:

  1. User assistance is required to create a webhook. They cannot be created automatically;
  2. Since webhooks have infinite lifetime, webhook URL's must be strictly controlled. Any leak can create a vulnerability within the scope of access permissions granted to the webhook. In practice it means this method cannot be used for public applications on the Bitrix24.Market;
  3. A number of REST methods cannot be used with webhooks because they require application context while webhooks have no awareness of Bitrix24 application. These methods include Bitrix24 user interface extension calls, telephony events, some of the chatbot events etc.).

Despite these restrictions, webhooks are ideal for quick implementation of business-specific features.

  Creating an Inbound Webhook

Inbound Webhook is used to handle data of your Bitrix24 account via API.

The inbound webhook can be created in the Developer resources Starting from REST module version 20.5.0, a new Developer resource tab is available in the left-side main menu. It contains fast and easy integration tools that improve your Bitrix24 usability.

Learn more...
(Developer resources > Common use cases > Other > Inbound webhook).

After opening the webhook section, you can proceed with the following actions:

  • change webhook name;
  • Select REST API method in the Request builder (you can read method description and download a complete code example with the necessary parameters to execute requests);
  • check if webhook is operational, by clicking on Execute;
  • assign access permissions for individual Bitrix24 modules and tools.

Request builder contains a sample URL that must be used when sending data from external third-party system to Bitrix24

URL consists of:

  • bitrix24.com.business.portal - your Bitrix24 address name
  • /rest - indication that webhook operation is performed via REST
  • /1 - user ID who created the webhook
  • /173glortu42lvpju - secret key

    Attention! This code is confidential. Please, do not disclose it.

    Secret codes for webhooks of other users are unavailable for even a Bitrix24 user with administrator access permissions. When an administrator edits a webhook of another user, the secret key is reset and this administrator becomes this webhook's owner.

  • /crm.contact.get - a called method REST API Bitrix24 includes a cloud-based and self-hosted software products, created by Bitrix24, inc.

    Developers can create custom applications or integrations for Bitrix24 by using an open REST API that operates with both Bitrix24 Cloud and Self-hosted.

    Learn more...
    . In this case - method that returns a contact by an ID
  • .json - optional parameter ("transport"). may be skipped when creating new webhooks (uses .json by default). Indicates .json directly for complete software solutions
  • ?ID=42 - parameters, necessary for a specific method. In this case, an indentifier. Parameters are indicated after a question mark and are separated by & character.

Creating inbound web hooks prior to REST module version 20.5.0

  Creating an Outbound Webhook

Attention! Bitrix24 Self-hosted editions require a valid and active license to use outbound webhooks. This type of webhooks will not work in demo mode.

The outbound webhook can be created in the Developer resources Starting from REST module version 20.5.0, a new Developer resource tab is available in the left-side main menu. It contains fast and easy integration tools that improve your Bitrix24 usability.

Learn more...
(Developer resources > Common use cases > Other > Outbound webhook).

Outbound webhook is used for getting information about events, occurring in your Bitrix24.

After opening the webhook section, you can proceed with the following actions:

  1. change webhook name;
  2. indicate your handler's URL - for a page at the third-party resource, queried by the webhook;
  3. select an event that will initialize the webhook.
  4. When creating an outbound webhook, a token in a form of a string, consisting of random characters is retrieved. This code allows to check inside the handler to ensure that the handler is authentically called by your Bitrix24.

  5. Specify the following code at the handler's page:

    Example of handler code for the event ONCRMDEALUPDATE

    <?
    
    print_r($_REQUEST);
    writeToLog($_REQUEST, 'incoming');
    
    /**
     * Write data to log file.
     *
     * @param mixed $data
     * @param string $title
     *
     * @return bool
     */
    function writeToLog($data, $title = '') {
     $log = "\n------------------------\n";
     $log .= date("Y.m.d G:i:s") . "\n";
     $log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
     $log .= print_r($data, 1);
     $log .= "\n------------------------\n";
     file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
     return true;
    } 

    To check if everything is ok, open any deal for editing and save the updates. The log will show approximately the following history:

    2017.01.17 12:58:29
    incoming
    Array
    (
        [event] => ONCRMDEALUPDATE
        [data] => Array
            (
                [FIELDS] => Array
                    (
                        [ID] => 662
                    )
    
            )
    
        [ts] => ххх
        [auth] => Array
            (
                [domain] => ххх.bitrix24.com
                [client_endpoint] => https://ххх.bitrix24.com/rest/
                [server_endpoint] => https://oauth.bitrix.info/rest/
                [member_id] => ххх
                [application_token] => ххх
            )
    
    )


Courses developed by «Bitrix», Inc.