Inbound and outbound webhooks

The best way to handle these tasks is to use Bitrix24's REST API, along with the handy tools in the “Developer resources” section.

“Developer resources” section

In this section, you'll find pre-built examples for typical tasks, like the "Import and Export Data" section and its "Import Customers" example.

Request builder

The “Developer resources” also includes a “Request builder” block that makes it easy to make REST API requests directly from the interface. You'll be able to select from different methods and configure the appropriate parameters. The REST API methods guide provides information on specific parameters.

Once you've made a request, you'll receive a response from Bitrix24 in JSON format. In the future, we'll delve into how to analyse these responses at the code level. For now, let's just focus on making a successful request and see the results in the CRM.

Inbound webhook and SDK CRest

To call REST methods from your own programming code, Bitrix24 also provides a ready-made example in PHP

This example includes the CRest SDK, which is available for download from Github. The example includes 5 files, including a settings file with authorization parameters, a CRest file with a PHP class for working with the REST API, a checkserver file to check if your webserver is configured correctly, an install.php file for future use, and an index.php file that you'll use to make REST API calls.

The checkserver file serves a crucial purpose in ensuring that our web server is correctly configured to run the PHP code of the example. After uploading the files to the server, we can now proceed to check if everything is in order.

To do this, we need to open a browser and type in the path to the checkserver file. The checker will then inform us if the example files require different permissions. We can then use the corresponding tool in our development environment, or a standalone FTP client or a file management panel on our hosting service provider, to set the required permissions.

The file install.php isn't necessary at this moment as we're not currently creating a local application.

However, the file index.php is useful. This file was generated when we downloaded the example and has now been reformatted for better readability. On line 4, we access the call method of the CRest class, which helps us make REST API calls.

To do this, we need to specify the method name, in this example, it's "crm.contact.add". Additionally, we need to specify the method parameters, in this case, it's the "FIELDS" parameter, an array with a list of different contact field values. Different REST methods have different parameters, which can be found in the documentation.

The result of the method call is stored in the array result, and its output is displayed.

To run the example, we need to open a browser and type in the corresponding address. If the example runs correctly, the result will show that a new contact with new ID was created, proving that we have successfully learned how to call REST API methods from our code.

Outbound webhook

In certain scenarios, it may be desirable for our automation to trigger itself when a user modifies data within Bitrix24. The "Outbound Webhook" tool serves this purpose in local integrations.

Navigate to the "Third-party system integrations" section and select the "Synchronize Customers" template. This pre-fabricated template subscribes to changes in any contact data within the CRM, allowing us to receive updates on those changes. .

Download the provided example and upload it to your server, being mindful of the necessary URL for file access.

Return to the Bitrix24 interface, where you will notice a pre-prepared incoming webhook to retrieve contact details. Our current focus, however, is on the "Outbound webhook" block.

In the "Handler URL" field, specify the URL to which Bitrix24 will send the "signal" indicating a data-related event has occurred. In the "Events" field, select "OnCRMContactUpdate" to track changes to CRM contacts.

Having set the handler address and selected the relevant event, let us examine the example code. This code employs the SDK previously discussed, with the primary distinction being the handler.php file set in the "Handler URL" field.

The handler receives a POST request from Bitrix24 containing event data. In this example, we save this data to a file, then manually modify a CRM contact, and return to the code to observe the generated file with the event data.

Bitrix24 provides information on the triggered outbound webhook event, including the modified contact's identifier, the secret application token, and various portal data of little relevance at this time.

With an understanding of the POST request data structure from Bitrix24, we can return to the example code. The first step is to verify the presence of the secret application_token parameter, ensuring the call originates from our Bitrix24 portal.

Next, we verify the event as an "ONCRMCONTACTUPDATE". This conditional check allows us to differentiate processing for various events through the same handler file.

Using the incoming webhook, we then run a request to Bitrix24 to retrieve all information regarding the modified contact, whose ID is acquired from the POST request data.

In this case, we simply log the retrieved information to a file, but in practice, the data could be passed to an external system, modified, and returned to Bitrix24 for further automated processing as needed.