Views: 466
Last Modified: 17.08.2020

Introduction

To make the long and windy story short: a webhook obtains through the Bitrix24 user interface an authentication key that an application can use to call REST methods; unlike OAuth 2.0 tokens, these 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 Marketplace;
  3. 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

  1. Click Add Webhook and select Inbound Webhook in the menu.
  2. Fill out the fields:
    • Name and Description.
    • Access permissions: select the modules your webhook needs access to.
  3. Click Save. The system will show the webhook authorization code:

    Attention! This code is strictly confidential. Please make sure you keep it out of reach of any third party who doesn't need to know it.
  4. Below the code is an example of URL you will have to use to send data from an external system to Bitrix24:
    https://********.bitrix24.com/rest/1/83te1pjdphsa9u15/profile/
    где:
    • ******** - is the name of your Bitrix24;
    • /rest/ - tells the system to categorize the URL as a webhook call;
    • /1/ - is the ID of a user whose credentials were used when creating the webhook. The webhook inherits all permissions of this user.
    • /83te1pjdphsa9u15/ - is the secret code;
    • /profile/ - specifies the REST method you want to call. Please refer to REST API documentation for the list of methods.
  5. Use this URL to call Bitrix24 from external system.

    Now, assume you want to create a lead from a web form on your site. Open settings.php for editing and find the C_REST_WEB_HOOK_URL constant to the URL you obtained when creating the webhook. Next, open the index.php from the constant to the URL you obtained when creating the webhook. Next, open the index.php from the SDK CRest for editing and the following code (it creates a $queryData array to define the lead parameters).

    Attention! This example uses SDK CRest. You have to open the strong>checkserver.phpyou have uploaded to the server in your browser to make sure your server configuration is correct Learn more here.

    Code example for query to Bitrix24
    <?php
    require_once(__DIR__ . '/crest.php');

    $defaults = [
    'first_name' => '',
    'last_name' => '',
    'phone' => '',
    'email' => ''
    ];

    if (array_key_exists('saved', $_REQUEST))
    {
    $defaults = $_REQUEST;

    $queryData = [
    'fields' => [
    'TITLE' => $_REQUEST['first_name'] . ' ' . $_REQUEST['last_name'],
    'NAME' => $_REQUEST['first_name'],
    'LAST_NAME' => $_REQUEST['last_name'],
    'STATUS_ID' => 'NEW',
    'OPENED' => 'Y',
    'ASSIGNED_BY_ID' => 1,
    'PHONE' => [['VALUE' => $_REQUEST['phone'], 'VALUE_TYPE' => 'WORK']],
    'EMAIL' => [['VALUE' => $_REQUEST['email'], 'VALUE_TYPE' => 'WORK']],
    ],
    'params' => ['REGISTER_SONET_EVENT' => 'Y'],
    ];

    $result = CRest::call(
    'crm.lead.add',
    $queryData
    );

    if (array_key_exists('error', $result))
    {
    echo 'Error saving lead: ' . $result['error_description'];
    }
    else
    {
    echo 'Data has been saved';
    }
    }
    ?>
    <form method="post" action="">
    Name: <input type="text" name="first_name" size="15" value="<?=$defaults['first_name']?>"><br/>
    Last name: <input type="text" name="last_name" size="15" value="<?=$defaults['last_name']?>"><br/>
    Phone: <input type="phone" name="phone" value="<?=$defaults['phone']?>"<
    E-mail: <input type="email" name="email" value="<?=$defaults['email']?>"><br/>
    <input type="hidden" name="saved" value="yes">
    <input type="submit" value="Send">
    </form>

  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.

  1. Click Add Webhook and select Outbound Webhook in the menu.
  2. Fill out the fields:
    • Handler address: enter the URL of the page on a remote system the webhook will call.
    • Name and Description.
    • Event type: select the event that will activate the webhook.
  3. Click Save. The system will show the webhook authorization code you will use to verify the webhook is called by your Bitrix24.
  4. Add the following code to the handler page:

    (this example processes the ONCRMDEALUPDATE event)

    <?
    
    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 make sure your webhook works, open any deal for editing and save the changes. The log will show something like this:

    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.