Documentation

WebHooks

WebHooks - simplified variant of REST-events and REST-commands, without the need to create an app.

Webhooks can be conveniently used to quickly connect a specific Bitrix24 account to a specific internal system or a separately employed feedback form. They also can be used for sending reports from your inventory system to Activity Stream as well.

Inbound and Outbound webhooks can be created on Applications > Webhooks page.

Create Inbound Webhook

  1. Select Inbound Webhook in the dropdown Add Webhook menu.
  2. Fill in the following fields in the opened form:
    • Name and Description - random data.
    • Access Rights - indicate access rights to specific modules for webhooks. Multiple selection is available.
  3. After saving, webhook authorization code will appear:  

    Attention! This code is confidential. Do not disclose it.
  4. Jointly with the code, a URL sample will be provided, which shall be used when sending data from third-party system to Bitrix24:
    https://********.bitrix24.com/rest/1/83te1pjdphsa9u15/profile/
    where:
    • ******** - your account name;
    • /rest/ - specify to the system, that this address pertains to webhooks;
    • /1/ - user ID, who created webhook. This webhook will work under the authorization rights of this user.
    • /83te1pjdphsa9u15/ - secret code;
    • /profile/ - REST method, which you want to execute, by accessing the webhook. Developer should personally select a method from REST API depending on objectives of created webhook.
  5. Request from external system to the specified Bitrix24 address.

    Let's examine an example of such request with the task to create a Lead from a form. A URL should be generated in the$queryUrlvariable. Parameters should be formulated to create a Lead in the $queryData variable. After preparatory steps, request to Bitrix24 should be executed via curl_exec. Returned JSON result is processed:

    Example of code for request to Bitrix24
    <?
    /**
     * 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;
    }
    
    $defaults = array('first_name' => '', 'last_name' => '', 'phone' => '', 'email' => '');
    
    if (array_key_exists('saved', $_REQUEST)) {
     $defaults = $_REQUEST;
     writeToLog($_REQUEST, 'webform');
    
     $queryUrl = 'https://restapi.bitrix24.com/rest/1/31uhq2q855fk1foj/crm.lead.add.json';
     $queryData = http_build_query(array(
     'fields' => array(
     "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" => array(array("VALUE" => $_REQUEST['phone'], "VALUE_TYPE" => "WORK" )),
     "EMAIL" => array(array("VALUE" => $_REQUEST['email'], "VALUE_TYPE" => "WORK" )),
     ),
     'params' => array("REGISTER_SONET_EVENT" => "Y")
     ));
    
     $curl = curl_init();
     curl_setopt_array($curl, array(
     CURLOPT_SSL_VERIFYPEER => 0,
     CURLOPT_POST => 1,
     CURLOPT_HEADER => 0,
     CURLOPT_RETURNTRANSFER => 1,
     CURLOPT_URL => $queryUrl,
     CURLOPT_POSTFIELDS => $queryData,
     ));
    
     $result = curl_exec($curl);
     curl_close($curl);
    
     $result = json_decode($result, 1);
     writeToLog($result, 'webform result');
    
     if (array_key_exists('error', $result)) echo "Error saving Lead: ".$result['error_description']."
    ";
    }
    
    ?>
    <fo rm method="post" action="">
        First 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/>
        Telephone: <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>

    Attention! Example is for illustration only. It's not recommended to use copy/paste.

Create Outbound Webhook

  1. Select Outbound Webhook in the dropdown Add Webhook menu.
  2. Fill in the following fields in the opened form:
    • Handled address - page on a third-party site, to which webhook will send requests.
    • Name and Description - random data.
    • Event type - specify the event, for which the webhook will be initialized.
  3. After webhook is saved, Authorization code will be displayed as a line of random symbols. This code will allow to check inside the handler, if it is true that your Bitrix24 invoke the handler.
  4. Input the code on the handler page:

    Example of handler code for 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 verify, open any Deal to edit and save changes. The log will show the approx. history:

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

Providers

From REST 17.0.16 version onwards, it is possible to execute outbound webhooks and bypass authorization via oauth.bitrix.info and the queue, associated with it. For example, for accounts and applications, located predominantly inside the network without the external access.

Example for invoke all the handlers with address 192.168.*.* directly without any authorization data:

\Bitrix\Main\Loader::includeModule('rest');

class MyEventProvider extends \Bitrix\Rest\Event\ProviderOAuth
{
   public function send(array $queryData)
   {
      $http = new \Bitrix\Main\Web\HttpClient();
      foreach($queryData as $key => $item)
      {
         if(preg_match('/192\.168\./', $item['query']['QUERY_URL'])) // directly sending handlers, having  192.168. in the address
         {
            $http->post($item['query']['QUERY_URL'], $item['query']['QUERY_DATA']);
            unset($queryData[$key]);
         }
      }

      if(count($queryData) > 0)
      {
         parent::send(array_values($queryData)); // all the rest is to be sent via the standard mechanism
      }
   }
}

\Bitrix\Rest\Event\Sender::setProvider(MyEventProvider::instance());

See Also

Fast Bitrix24 Integration: Webhook Street Magic

User Comments

User comments are not part of official documentation. Use information provided by other users in the comments at your own risk.

The User Comments section is not to be used as a feature discussion board. Only registered users can post comments. Your comment will be visible once it has been approved by the moderator.
© «Bitrix Inc.», 2001-2020, «Bitrix Inc.», 2020