How to properly format fields array in Bitrix24 webhook

Proper Field Array Formatting in Bitrix24 Webhooks

Correct formatting of field arrays in Bitrix24 webhooks requires the use of double square brackets to pass multiple values. The basic syntax for passing a field array is: fields[[field_name]]=value or through a JSON structure with a fields object containing key-value pairs.

Contents

• Basic Webhook Field Syntax
• Formatting in the Bitrix24 Interface
• Examples of Proper Formatting
• Common Errors and Their Solutions
• Practical Code Examples
• Testing Recommendations

Basic Webhook Field Syntax

When working with Bitrix24 webhooks, there are two main ways to format fields:

1. URL Parameters with Double Brackets

According to the official Bitrix24 documentation, when passing field arrays through URL parameters, use the syntax with double square brackets:

fields[[TITLE]]=Lead Name
fields[[COMPANY_NAME]]=Company Name
fields[[PHONE][0][VALUE]]=+79001234567

Each field is enclosed in double brackets [[ ]] so that Bitrix24 correctly interprets the data structure.

2. JSON Format with fields Object

For programmatic integration, use JSON format:

{
  "fields": {
    "TITLE": "Lead Name",
    "COMPANY_NAME": "Company Name",
    "PHONE": [{
      "VALUE": "+79001234567",
      "VALUE_TYPE": "WORK"
    }]
  }
}

Important: For complex fields such as phone or email, a nested structure with value type specification is required.

Formatting in the Bitrix24 Interface

Setting Parameters in the Interface

1. In the “Webhooks” section, select an incoming webhook
2. In the parameters (Params) for each field, use the following format:
   • Key: [[field_name]]
   • Value: field value

Example Setup in the Interface

Examples of Proper Formatting

Example 1: Simple Fields

fields[[TITLE]]=Lead Name
fields[[COMPANY_NAME]]=Company Name
fields[[COMMENTS]]=Deal Comment

Example 2: Phone Field

For phone numbers, a structure with value type is required:

fields[[PHONE][0][VALUE]]=+79001234567
fields[[PHONE][0][VALUE_TYPE]]=WORK
fields[[PHONE][1][VALUE]]=+79009876543
fields[[PHONE][1][VALUE_TYPE]]=MOBILE

Example 3: Email Field

fields[[EMAIL][0][VALUE]]=user@example.com
fields[[EMAIL][0][VALUE_TYPE]]=WORK

Example 4: User Array

fields[[ACCOMPLICES][0]]=1
fields[[ACCOMPLICES][1]]=3

Common Errors and Their Solutions

Error 1: Incorrect Number of Brackets

Incorrect:

fields[ TITLE ] = value  // single brackets

Correct:

fields[[ TITLE ]] = value  // double brackets

Error 2: Missing Structure for Complex Fields

Incorrect:

fields[PHONE] = +79001234567  // without type structure

Correct:

fields[[PHONE][0][VALUE]] = +79001234567
fields[[PHONE][0][VALUE_TYPE]] = WORK

Error 3: Incorrect URL Encoding

When passing through URL, ensure special characters are properly encoded:

fields[[COMMENTS]] = Text%20with%20spaces

Practical Code Examples

PHP Example

<?php
// Forming data for the webhook
$queryData = http_build_query(array(
    'fields' => array(
        "TITLE" => "Website Lead",
        "COMPANY_NAME" => "Test Company",
        "PHONE" => array(
            array(
                "VALUE" => "+79001234567",
                "VALUE_TYPE" => "WORK"
            )
        )
    )
));

// Webhook URL
$queryUrl = "https://your-portal.bitrix24.com/rest/your-token/crm.lead.add.json";

// Sending the request
$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);
?>

JavaScript Example (fetch)

const webhookUrl = 'https://your-portal.bitrix24.com/rest/your-token/crm.lead.add.json';

const data = {
    fields: {
        TITLE: "Form Lead",
        COMPANY_NAME: "Client Company",
        PHONE: [{
            VALUE: "+79001234567",
            VALUE_TYPE: "WORK"
        }]
    }
};

fetch(webhookUrl, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result));

Testing Recommendations

1. Use the Test Interface

Bitrix24 provides an interface for testing webhooks:

• Go to webhook settings
• Click “Test”
• Fill in the fields in the correct format

2. Step-by-Step Verification

1. First test simple fields (TITLE, COMPANY_NAME)
2. Then add complex fields (PHONE, EMAIL)
3. Check operation with user arrays

3. Error Logging

Enable logging to track errors:

// Example of logging in PHP
file_put_contents('webhook_log.txt', date('Y-m-d H:i:s') . " - " . $result . PHP_EOL, FILE_APPEND);

4. Data Validation

Before sending, ensure all required fields are filled and have the correct format.

Sources

1. Create webhooks and apps in Bitrix24 - Official documentation on field formatting using fields[[field]]
2. Inbound and outbound webhooks - Bitrix24 Helpdesk - Comprehensive guide to working with webhooks
3. Bitrix sending and receiving webhooks / ChatApp - Practical examples of field formatting
4. Working with a lead in Bitrix24 using the API - Code examples for working with webhooks
5. Bitrix24 - Webhook how to get data phone in array - Stack Overflow discussion on proper phone field structure

Conclusion

Proper formatting of field arrays in Bitrix24 webhooks requires attention to detail:

• Always use double square brackets [[ ]] for simple fields
• For complex fields (phone, email), use a nested structure with value type specification
• Test complex fields step by step, starting with simple ones
• Use the official Bitrix24 documentation as your primary information source

By following these rules, you can avoid most errors when passing data through Bitrix24 webhooks and ensure stable integration performance.