Overview of Events When Working with Custom Field Settings

Events allow applications to respond to changes in near real-time: receiving notifications about the addition, update, or deletion of custom field settings.

Detailed information on working with events is described in the article Concept and Benefits of Event Processing.

Quick navigation: all events

How to Receive EventsHow to Receive Events

You can subscribe to custom field settings events through:

• outgoing webhook
• application and the event.bind method

An example of a handler code for an event is described in the article How to Test Your Handler for Processing Bitrix24 Events.

The case of the event name does not matter when subscribing: event.bind accepts both onCrmTypeUserFieldAdd and ONCRMTYPEUSERFIELDADD. In event.get responses and in the event key of the event itself, the name always arrives in uppercase.

The events of this section require the crm scope — they are registered by the CRM module. The userfieldconfig.* methods require a different set: userfieldconfig and the module scope from moduleId. An application that both subscribes to the events and reads field settings needs both scopes.

Which Objects Trigger the EventsWhich Objects Trigger the Events

The events are triggered for custom fields of three CRM objects.

The events of this section do not arrive for custom fields of other objects and modules:

• changes to fields in Business Automation processes with moduleId=rpa and in inventory management documents with moduleId=catalog do not send events
• the events of this section do not arrive for fields of legacy invoices either: those have their own events with the codes onCrmInvoiceUserField*

Custom Field Events of Other CRM ObjectsCustom Field Events of Other CRM Objects

Leads, contacts, companies, deals, estimates, and requisites have their own custom field events:

• Overview of Events When Working with Custom Lead Fields
• Overview of Events When Working with Custom Contact Fields
• Overview of Events When Working with Company User Fields
• Overview of Events When Working with Custom Deal Fields
• Overview of Events When Working with Custom Fields in Estimates
• Overview of Events When Working with Requisites

For requisites, the custom field events belong to the common requisite events section together with the events of the requisite itself and of bank details.

What the Handler ReceivesWhat the Handler Receives

The events pass the custom field identifier, the object it belongs to, and its code in the data.FIELDS object:

{
            "event": "ONCRMTYPEUSERFIELDUPDATE",
            "data": {
                "FIELDS": {
                    "ID": "6977",
                    "ENTITY_ID": "CRM_13",
                    "FIELD_NAME": "UF_CRM_13_1742999523"
                }
            }
        }
        

The example shows only the meaningful part of the request. In addition to event and data, the handler receives three more top-level keys:

• event_handler_id — identifier of the event handler
• ts — date and time the event was sent from the queue
• auth — authorization parameters and information about the account where the event occurred

The full payload with all keys is shown on the event pages, for example onCrmTypeUserFieldAdd. To make sure the request came from Bitrix24, match auth.application_token and auth.member_id against the values of your application.

The event is delivered as a POST request, so the values inside data.FIELDS arrive as strings. Cast ID to a number if you compare it with identifiers from method responses.

The composition of FIELDS is the same for all four events. The field type, its settings, and the list of values are not passed in the event — retrieve them with the userfieldconfig.get method by passing the received ID together with moduleId = crm. This method requires the userfieldconfig scope in addition to the crm scope the application subscribes to the event with.

After the onCrmTypeUserFieldDelete event, the method returns an error with an empty code and the text You are not allowed to view custom field settings. It returns the same error when there are not enough rights to view the field, so the error code does not let you tell a deleted field from a rights denial. The remaining errors are covered on the userfieldconfig.get page.

Which Events Arrive TogetherWhich Events Arrive Together

A single action on a field of the list type enumeration sends one or two events:

These cases cannot be distinguished by the contents of data — all events carry the same three keys. If the handler is subscribed to both onCrmTypeUserFieldUpdate and onCrmTypeUserFieldSetEnumValues, guard against processing the same ID twice.

The events arrive only for actions on the field itself. When an entire smart process is deleted, its custom fields disappear as well, but onCrmTypeUserFieldDelete is not sent for them — track such cases with the onCrmTypeDelete event.

Server Availability for Sending and Receiving EventsServer Availability for Sending and Receiving Events

The event handler server must be accessible from the outside. To configure the accessibility of the event handler server and application, refer to the article Required network access.

For cloud Bitrix24, no additional configuration is required. For on-premise Bitrix24, configure accessibility on the server or hosting according to the article Required network access.

Overview of EventsOverview of Events

Scope: crm

Who can subscribe: any user

Continue LearningContinue Learning

• Custom Field Settings: Overview of Methods
• Event Handler
• Register a New Event Handler event.bind
• Overview of Events When Working with CRM Custom Types
• Overview of Events When Working with Smart Process Elements