Handling Events
REST API inferface allows developer to specify handlers for server events.
Event handler is a URL to which the system sends a query after a user performs a requested action on the Intranet hosting the application. Because queries will be sent from Bitrix24 servers, any URL must be accessible for external GET/POST queries.
The handler receives the following data on input.
Query fields | Description |
---|---|
event | Specifies the event name. |
data | An array containing the event data. Depends on the event contents. |
auth | Contains the authentication information. |
The handler:
- can use the received authentication information to send requests to REST API;
- can be installed only by a user having administrative privileges.
Note: when an event hander needs to query REST API to handle data, it's strongly recommended to use the passed authorization data specifically for this purpose instead of the data saved on the side of the app.
When installing a handler, the application can specify a user, whose credentials will be used by the event handler for authentication. By default, the event handler will be authenticated as a user whose actions triggered the event.
Notice: event handler is not called immediately after an event had occurred. It will be activated after some time which depends on a current server load.
To get a list of available events, use the REST method: events.
To install an event handler, use the event.bind method, or the JS library function: BX24.callBind.
To uninstall a previously set event handler, use the event.unbind method, or the JS library function: BX24.callUnbind.
To enable an application to access a specific event, a corresponding access permission has to be requested when registering an application version.
An application can install as many handlers for the same event as needed, provided that each of these handlers is installed for a different user. Furthermore, a handler may or may not be called which depends on the access permission of a user whose authorization is used to activate a handler.
The event names are case-insensitive.
Attention! When uninstalling an application or registering a new version, all the previous handlers are deleted.
Example
Application installation event
array( 'event' => 'ONAPPINSTALL', 'data' => array( 'VERSION' => '1', 'LANGUAGE_ID' => 'en', ), 'ts' => '1466439714', 'auth' => array( 'access_token' => 's6p6eclrvim6da22ft9ch94ekreb52lv', 'expires_in' => '3600', 'scope' => 'entity,im', 'domain' => 'portal.bitrix24.com', 'server_endpoint' => 'https://oauth.bitrix.info/rest/', 'status' => 'F', 'client_endpoint' => 'https://accountname.bitrix24.com/rest/', 'member_id' => 'a223c6b3710f85df22e9377d6c4f7553', 'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8', 'application_token' => '51856fefc120afa4b628cc82d3935cce', ), )
All REST Events
Event | is Called | Webhook support |
---|---|---|
Application events | ||
OnAppInstall | Event for installing an application | |
OnAppUpdate | Event for updating an application. | |
OnAppUninstall | Event for deleting an application | |
OnAppPayment | Event for application payment | |
OnAppMethodConfirm | Event is called when the account administrator permission allows to use methods, requiring confirmation | |
OnAppTest | ||
Bot platform events | ||
OnImBotMessageAdd | Event initiated when chatbot receives a message. | |
OnImBotMessageUpdate | Event to update message by chatbot. | |
OnImBotMessageDelete | Event to delete message by chatbot. | |
OnImBotJoinChat | Event initiated when chatbot receives information that it has joined a chat (or private chat). | |
OnImBotDelete | Event initiated when chatbot is deleted. | |
OnImCommandAdd | Event initiated when chatbot receives a command. | |
CRM Events | ||
Invoices | ||
onCrmInvoiceAdd | when creating an invoice | Yes |
onCrmInvoiceDelete | when delving an invoice | Yes |
onCrmInvoiceSetStatus | when modifying invoice status | Yes |
onCrmInvoiceUpdate | when updating an invoice | Yes |
onCrmInvoiceUserFieldAdd | when adding an invoice user field | Yes |
onCrmInvoiceUserFieldUpdate | when modifying an invoice user field | Yes |
onCrmInvoiceUserFieldDelete | when deleting an invoice user field | Yes |
onCrmInvoiceUserFieldSetEnumValues | when modifying set of values for the list-type user field within invoice | Yes |
onCrmInvoiceRecurringAdd | when creating new recurring invoice | Yes |
onCrmInvoiceRecurringUpdate | when updating a recurring invoice | Yes |
onCrmInvoiceRecurringDelete | when deleting a recurring invoice | Yes |
onCrmInvoiceRecurringExpose | when issuing new invoice based in recurring invoice | Yes |
Products | ||
onCrmProductAdd | when creating a product | Yes |
onCrmProductUpdate | when updating a product | Yes |
onCrmProductDelete | when deleting a product | Yes |
onCrmProductPropertyAdd | when creating a product property | Yes |
onCrmProductPropertyUpdate | when updating a product property | Yes |
onCrmProductPropertyDelete | when deleting a product property | Yes |
onCrmProductSectionAdd | при добавлении раздела свойств товара | Yes |
onCrmProductSectionUpdate | при изменении раздела свойств товара | Yes |
onCrmProductSectionDelete | when deleting a product property section | Yes |
Leads | ||
onCrmLeadAdd | when creating a lead | Yes |
onCrmLeadUpdate | when updating a lead | Yes |
onCrmLeadDelete | when deleting a lead | Yes |
onCrmLeadUserFieldAdd | when adding a user field | Yes |
onCrmLeadUserFieldUpdate | when modifying a user field | Yes |
onCrmLeadUserFieldDelete | when deleting a user field | Yes |
onCrmLeadUserFieldSetEnumValues | when modifying set of values for list-type user field | Yes |
Deals | ||
onCrmDealAdd | when crating a deal | Yes |
onCrmDealUpdate | when updating a deal | Yes |
onCrmDealDelete | when deleting a deal | Yes |
onCrmDealUserFieldAdd | when adding user field | Yes |
onCrmDealUserFieldUpdate | when modifying user field | Yes |
onCrmDealUserFieldDelete | when deleting user field | Yes |
onCrmDealUserFieldSetEnumValues | when modifying set of values for the list-type use field | Yes |
onCrmDealRecurringAdd | цру creating new recurring deal | Yes |
onCrmDealRecurringUpdate | when updating a recurring deal | Yes |
onCrmDealRecurringDelete | when deleting a recurring deal | Yes |
onCrmDealRecurringExpose | when creating a new deal from a recurring deal | Yes |
Companies | ||
onCrmCompanyAdd | when creating a company | Yes |
onCrmCompanyUpdate | when updating a company | Yes |
onCrmCompanyDelete | when deleting a company | Yes |
onCrmCompanyUserFieldAdd | when adding a company user field | Yes |
onCrmCompanyUserFieldUpdate | when modifying a company user field | Yes |
onCrmCompanyUserFieldDelete | when deleting a company user field | Yes |
onCrmCompanyUserFieldSetEnumValues | when modifying set of values for the list-type company field | Yes |
Contacts | ||
onCrmContactAdd | when creating a contact | Yes |
onCrmContactUpdate | when updated a contact | Yes |
onCrmContactDelete | when deleting a contact | Yes |
onCrmContactUserFieldAdd | when adding a user field | <Yes |
onCrmContactUserFieldUpdate | when modifying a contact user field | Yes |
onCrmContactUserFieldDelete | when deleting a contact user field | Yes |
onCrmContactUserFieldSetEnumValues | when modifying set of values for the list-type contact user field | Yes |
Currencies | ||
onCrmCurrencyAdd | when creating a currency | Yes |
onCrmCurrencyUpdate | when updating a currency | Yes |
onCrmCurrencyDelete | when deleting a currency | Yes |
Activities | ||
onCrmActivityAdd | when creating an activity | Yes |
onCrmActivityUpdate | when updating an activity | Yes |
onCrmActivityDelete | when deleting an activity | Yes |
Quotes | ||
onCrmQuoteAdd | when creating a quote | Yes |
onCrmQuoteUpdate | when updating a quote | Yes |
onCrmQuoteDelete | when deleting a quote | Yes |
onCrmQuoteUserFieldAdd | when adding a quote user field | Yes | /tr>
onCrmQuoteUserFieldDelete | when deleting a quote user field | Yes |
onCrmQuoteUserFieldUpdate | when modifying a quote user field | Yes |
onCrmQuoteUserFieldSetEnumValues | when modifying set of values for the list-type user field | Yes |
Requisites | ||
onCrmRequisiteAdd | When adding a requisite | Yes |
onCrmRequisiteUpdate | When modifying a requisite | Yes |
onCrmRequisiteDelete | When deleting a requisite | Yes |
onCrmRequisiteUserFieldAdd | when adding a requisite user field | Yes |
onCrmRequisiteUserFieldUpdate | when modifying a requisite user field | Yes |
onCrmRequisiteUserFieldDelete | when deleting a requisite user field | Yes |
onCrmRequisiteUserFieldSetEnumValues | when modifying set of values for the list-type user field | Yes |
onCrmBankDetailAdd | when adding bank details | Yes |
onCrmBankDetailUpdate | when updating bank details | Yes |
onCrmBankDetailDelete | when deleting bank details | Yes |
[link=10171497]onCrmAddressRegister | who adding an address | Yes |
onCrmAddressUnregister | when deleting an address | Yes |
Measurement Units | ||
onCrmMeasureAdd | when adding a unit of measurement | Yes |
onCrmMeasureUpdate | when updating a unit of measurement | Yes |
onCrmMeasureDelete | when deleting a unit of measurement | Yes |
Timeline | ||
onCrmTimelineCommentAdd | when adding a new timeline comment | Yes |
onCrmTimelineCommentUpdate | when updating a new timeline comment | Yes |
onCrmTimelineCommentDelete | when deleting a new timeline comment | Yes |
Telephony Events | ||
OnVoximplantCallInit | when initializing a call (inbound or outbound). | |
OnVoximplantCallStart | when starting telephone conversation (operator responds for inbound call and call recipient responds to outbound call). | |
OnVoximplantCallEnd | when conversation ends (history entry). | |
OnExternalCallStart | when user clicks on a phone number in CRM objects for an outbound call. | Yes |
OnExternalCallBackStart | when filling out CRM callback form. | Yes |
Task Events | ||
OnTaskAdd | when adding a task. | Yes |
OnTaskUpdate | when updating a task. | Yes |
OnTaskDelete | when deleting a task. | Yes |
OnTaskCommentAdd | when adding a task comment. | Yes |
OnTaskCommentUpdate | when updating a task comment. | Yes |
OnTaskCommentDelete | when deleting a task comment. | Yes |
User events | ||
OnUserAdd | When adding a user to Bitrix24. | Yes |
Calendar Events for External Messenger Connectors | ||
OnImConnectorLineDelete | Deletes Open Channel. | |
OnImConnectorMessageAdd | New Open Channel message. | |
OnImConnectorMessageUpdate | Open Channel message update. | |
OnImConnectorMessageDelete | Deletes Open Channel message. | |
Calendar events | ||
OnCalendarEntryAdd | when adding an event. | Yes |
OnCalendarEntryUpdate | when updating an event. | Yes |
OnCalendarEntryDelete | when deleting an event. | Yes |
OnCalendarSectionAdd | when adding a calendar section (see CALENDAR_SECTION_ID). Also is shown when adding a resource. | Yes |
OnCalendarSectionUpdate | when updating a section/resource. | Yes |
OnCalendarSectionDelete | when deleting section/resource. | Yes |