Webhooks. Quickstart

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:

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

Creating an Inbound Webhook

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 > Other > Inbound webhook).

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

Creating inbound web hooks prior to REST module version 20.5.0

Click Add Webhook and select Inbound Webhook in the menu.
Fill out the fields:
- Name and Description.
- Access permissions: select the modules your webhook needs access to.
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.
Below 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/
where:
- ******** - 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.

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 checkserver.php you 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>

<? 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; }

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] => ххх ) )

Bitrix24 Applications

Description

Creating an Inbound Webhook

Creating an Outbound Webhook