Inbound and Outbound Webhooks

Webhooks are suitable for local integrations in a single Bitrix24 account. An inbound webhook calls REST API methods on behalf of the employee who created it. An outbound webhook sends a Bitrix24 event to your handler URL.

What to ChooseWhat to Choose

Inbound WebhookInbound Webhook

Choose an inbound webhook for internal integrations and quick checks when:

• you need to quickly test a method call in the browser, request builder, or with curl
• the integration works with only one Bitrix24 account
• requests must be executed on behalf of a specific employee
• you do not need an application interface, event handler, or solution installation on other Bitrix24 accounts

How an Inbound Webhook WorksHow an Inbound Webhook Works

Inbound webhook permissions are defined by the employee who created it and the selected scope list:

• an inbound webhook can be created by an administrator or by an employee for whom the administrator has allowed webhook creation
• the Bitrix24 account must have access to the REST API
• requests are executed within the scope selected in the webhook settings
• requests are executed with the permissions of the employee who created the webhook
• the webhook secret code is available only to the employee who created it. If an administrator edits another user's webhook, the secret code is updated and the administrator becomes the webhook owner
• some methods are not available through a webhook because they require the application context. For example, widget embedding methods such as placement.bind, some telephony methods, and some chatbot scenarios
• the inbound webhook mechanism supports an expiration date. If the expiration date has passed, the request stops working and returns an authorization error

How to Create an Inbound WebhookHow to Create an Inbound Webhook

Create webhooks in Applications > Developer resources. If a ready-made scenario fits your case, select it on the Common use cases tab and open its settings. If there is no suitable scenario, create an inbound webhook on the Common use cases > Other tab.

1. Open Applications > Developer resources
2. Go to Common use cases > Other > Inbound webhook
3. In the request builder, select a method and fill in parameters if required
4. Click Execute to test the call
5. In the Assign permissions section, select the required permissions and click Create

In the request builder, you can select a method, view the method and parameter descriptions, fill in parameters, execute the request, and download a ready-made PHP code example.

If the Inbound webhook item is missing, the permission to create webhooks is disabled. Ask the administrator to grant access to webhook creation.

Webhook URL StructureWebhook URL Structure

Example URL:

https://example.bitrix24.com/rest/1/xxxxxxxx/department.get.json?ID=42
        

The URL consists of several parts:

• example.bitrix24.com — your Bitrix24 address
• /rest — path to the REST API
• /1 — identifier of the employee who created the webhook
• /xxxxxxxx — webhook secret code
• /department.get — name of the called method
• .json — response format. This suffix can be omitted, json is used by default
• ?ID=42 — method parameters

How to Configure Access to Webhook Creation for EmployeesHow to Configure Access to Webhook Creation for Employees

An employee without administrator permissions cannot grant this access to themselves. An administrator can allow webhook creation for all employees or selected users.

1. Open Settings > Bitrix24 settings. The section is available only to employees with administrator permissions.
2. In the new window, go to Security > Bitrix24 integrations.
3. In the Who can create inbound webhooks field, click Add and select all employees or selected users

How to Quickly Test a Method with a GET RequestHow to Quickly Test a Method with a GET Request

On REST API method pages, webhook calls are shown as POST requests. A GET request can be executed in the browser address bar or in the request builder when creating an inbound webhook.

This format is suitable when you need to quickly test a simple call and see how parameters look in the URL.

General URL format:

https://{your-bitrix24}.bitrix24.com/rest/{user_id}/{webhook_code}/{method}.json
        

Example of a method without parameters:

https://example.bitrix24.com/rest/1/xxxxxxxx/profile.json
        

Example of a method with one parameter:

https://example.bitrix24.com/rest/1/xxxxxxxx/department.get.json?ID=1
        

Example of a method with an array of parameters:

https://example.bitrix24.com/rest/1/xxxxxxxx/user.get.json?FILTER[ACTIVE]=true&select[]=ID&select[]=NAME
        

What to Check Before Production UseWhat to Check Before Production Use

Before production launch, check that:

• the required method is available for the selected scope
• the employee who created the webhook has permissions for the required object
• your Bitrix24 account has access to the REST API
• requests are sent over HTTPS

Outbound WebhookOutbound Webhook

Choose an outbound webhook when:

• an external system must automatically learn about changes in Bitrix24
• synchronization must start after an object is created or changed
• it is enough to receive the event and object identifier, and detailed data can be requested with a separate method

How an Outbound Webhook WorksHow an Outbound Webhook Works

An outbound webhook does not call a method by itself. It passes an event to your handler, and the handler decides whether an additional REST API request is required:

• you select an event and handler URL
• when the event occurs, Bitrix24 sends a POST request to this URL
• the handler receives the event name, basic object data, and service authorization fields
• if full object data is required, the handler usually calls the corresponding method through an inbound webhook or an application

How to Create an Outbound WebhookHow to Create an Outbound Webhook

1. Open Applications > Developer resources
2. Go to Common use cases > Other > Outbound webhook
3. Specify your handler URL
4. Select the event the webhook should react to
5. Click Create and test the call after a test data change

The handler URL must be public and available from the external network. Do not specify localhost, local network addresses, or handlers with a self-signed SSL certificate.

When you create an outbound webhook, Bitrix24 shows a token. It is required so that the handler can verify that the request actually came from your Bitrix24 account.

What the Handler ReceivesWhat the Handler Receives

Data arrives as HTTP request parameters with the application/x-www-form-urlencoded type. In PHP, it is convenient to read them through $_REQUEST.

Example structure for the ONCRMDEALUPDATE event:

Array
        (
            [event] => ONCRMDEALUPDATE
            [data] => Array
                (
                    [FIELDS] => Array
                        (
                            [ID] => 662
                        )
                )
            [ts] => 1724140800
            [auth] => Array
                (
                    [domain] => example.bitrix24.com
                    [member_id] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                    [application_token] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                )
        )
        

Request parameters:

In a typical scenario, the handler takes the deal identifier from data[FIELDS][ID] and then calls the crm.item.get method with entityTypeId = 2 to retrieve full data.

How to Verify Request AuthenticityHow to Verify Request Authenticity

Compare the auth[application_token] value in the request with the token value shown in the outbound webhook settings. If the values do not match, the request cannot be considered trusted.

Outbound Webhook LimitationsOutbound Webhook Limitations

Before configuring an outbound webhook, consider that:

• in the on-premise version of Bitrix24, an active license is required for an outbound webhook
• outbound webhooks are not available in demo modes
• the handler URL must be available from the external network and accept POST requests
• for the on-premise version, you need to open the required network access

When a Webhook Is Not EnoughWhen a Webhook Is Not Enough

Choose a local application or OAuth 2.0 if:

• the integration must be installed on different Bitrix24 accounts
• you need an interface inside Bitrix24
• you need methods that work only in the application context
• you need centralized authorization management without passing the webhook URL

Continue LearningContinue Learning

• Developer resources in Bitrix24
• Local Applications
• Local Integrations: Use Case Scenarios
• How to Make Your First API Request
• Available Scopes in Bitrix24
• Complete OAuth 2.0 Authorization Protocol