Event on Task Addition OnTaskAdd

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: task

Who can subscribe: any user

The ONTASKADD event is triggered after a task is created.

Events will not be sent to the application until the installation is complete. Check the application installation

What the Handler Receives

Data is transmitted as a POST request

{
            "event": "ONTASKADD",
            "data": {
                "FIELDS_BEFORE": "undefined",
                "FIELDS_AFTER": {
                    "ID": 123
                },
                "IS_ACCESSIBLE_BEFORE": "N",
                "IS_ACCESSIBLE_AFTER": "undefined"
            },
            "ts": "1466439714",
            "auth": {
                "access_token": "s6p6eclrvim6da22ft9ch94ekreb52lv",
                "expires_in": "3600",
                "scope": "task",
                "domain": "some-domain.bitrix24.com",
                "server_endpoint": "https://oauth.bitrix.info/rest/",
                "status": "F",
                "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                "member_id": "a223c6b3710f85df22e9377d6c4f7553",
                "refresh_token": "4s386p3q0tr8dy89xvmt96234v3dljg8",
                "application_token": "51856fefc120afa4b628cc82d3935cce"
            }
        }

Required parameters are marked with *

parameter
type

Description

event*
string

Symbolic code of the event.

In this case — ONTASKADD

data*
object

An object containing data about the task addition event.

The structure is described below

ts*
timestamp

Date and time of the event sent from the event queue

auth*
object

Object containing authorization parameters and information about the account where the event occurred.

The structure is described below

Parameter Data[]

Name
type

Description

FIELDS_BEFORE*
undefined|object

Fields of the task before the event (detailed description provided below). If no task fields are available, this field will contain the value undefined

FIELDS_AFTER*
undefined|object

Fields of the task after the event (detailed description provided below). If no task fields are available, this field will contain the value undefined

IS_ACCESSIBLE_BEFORE*
string

Whether the task was accessible for reading before the event (detailed description provided below)

IS_ACCESSIBLE_AFTER*
string

Whether the task became accessible for reading after the event (detailed description provided below)

Field FIELDS_BEFORE

Name
type

Description

ID*
integer

Created task identifier

Field FIELDS_AFTER

Name
type

Description

ID*
integer

Created task identifier

Field IS_ACCESSIBLE_BEFORE

Name
type

Description

IS_ACCESSIBLE_BEFORE*
string

Possible values:

  • Y (Yes) — yes
  • N (No) — no
  • undefined — not defined or check was not performed

Field IS_ACCESSIBLE_AFTER

Name
type

Description

IS_ACCESSIBLE_AFTER*
string

Possible values:

  • Y (Yes) — yes
  • N (No) — no
  • undefined — not defined or check was not performed

Parameter auth

Required parameters are marked with *

Name
type

Description

access_token
string

Authorization token OAuth 2.0

expires_in
integer

Time in seconds until the token expires

scope*
string

Scope under which the event occurred

domain*
string

Address of Bitrix24 where the event occurred

server_endpoint*
string

Address of the Bitrix24 authorization server needed to refresh OAuth 2.0 tokens

status*
string

Status of the application that subscribed to this event:

  • L — local application
  • F — free mass-market application
  • D — demo version of a mass-market application
  • T — trial version of a mass-market application, time-limited
  • P — paid mass-market application

client_endpoint*
string

Common path for REST API method calls for Bitrix24 where the event occurred

member_id*
string

Identifier of Bitrix24 where the event occurred

refresh_token
string

Token for extending authorization OAuth 2.0

application_token*
string

Token for secure event handling

Authorization tokens are not always passed to the event handler. If the hit that initiated the event could not be linked to a specific Bitrix24 user, the tokens are not passed. Always check the contents of the auth key in the code.

It is recommended to store tokens obtained earlier during the application installation. Use them when working with the application interface in the form of embeds, widgets, and so on.

Code Examples

How to Use Examples in Documentation

// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (event.bind returns true on success)
        type BindEventResult = boolean
        
        try {
          const response = await $b24.actions.v2.call.make<BindEventResult>({
            method: 'event.bind',
            params: {
              event: 'onTaskAdd',
              handler: 'https://example.com/handler.php',
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Event bound successfully:', result)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function bindOnTaskAddEvent() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'event.bind',
                params: {
                  event: 'onTaskAdd',
                  handler: 'https://example.com/handler.php',
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Event bound successfully:', result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', bindOnTaskAddEvent)
        </script>
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'event.bind',
                    [
                        'event'   => 'onTaskAdd',
                        'handler' => 'https://example.com/handler.php',
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            // The data processing logic you need
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error binding event: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'event.bind',
            {
                "event": "onTaskAdd",
                "handler": "https://example.com/handler.php"
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.info(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'event.bind',
            [
                'event' => 'onTaskAdd',
                'handler' => 'https://example.com/handler.php'
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Continue Learning

Previous
Overview of Events
Next
When Updating a Task