# Activity and automation rule callback delivery

An activity or automation rule handler on a Black Hole subdomain gets reliable delivery: the platform queues the calls, wakes a sleeping server and retries. A handler on your own domain works as before — Bitrix24 calls it directly and does not retry.

Scope: `bizproc`

The mechanism has no endpoint of its own. It turns on automatically when you specify an address on a Black Hole subdomain in the `handler` field — when [registering an activity](/docs/entities/bizproc-activities/create), [registering an automation rule](/docs/entities/bizproc-robots/create) or when you change the handler of an activity or automation rule that is already registered.

## What happens on registration

The platform matches the subdomain in `handler` with your app server and stores the binding — the app, the activity or automation rule code, the server and the handler path. Bitrix24 stores the address of the platform receiver, not the one you passed. That is by design: the call arrives at the receiver, and the platform delivers it to the app at the same path you specified in `handler`. Only the path is taken from the address — a query string after `?` is not carried into the delivery, so pass the values you need through a separate handler path.

Activity codes and automation rule codes live in separate registries, so the same `code` can be registered both as an activity and as an automation rule: the platform keeps two separate bindings for them and never mixes the calls up.

If the subdomain does not exist, or the server behind it has been deleted or belongs to another app, registration is rejected with `400 SERVER_APP_MISMATCH`. Register the handler with the key of the app the server is linked to.

## What the handler receives

The platform sends the call as a POST request to the handler path in `application/x-www-form-urlencoded` format. The body is exactly what Bitrix24 would have sent on a direct call, `auth[application_token]` and `code` included — a handler written for a direct call needs no changes.

The platform waits up to 10 seconds for a response — a narrower window than the 30 seconds the [Gateway](/docs/infra/app-runtime) gives an app for a request through the subdomain. A `2xx` response counts as delivery — any other response or silence is a reason to retry. Move heavy work into the background and respond straight away.

A retry carries the same body, so the handler must be ready to see a call it has already processed: an app that answered at the twelfth second has done its work, but the platform did not wait for that answer and will retry the call. Filter out duplicate calls by `workflow_id` or `event_token`.

## When the retries run out

The retries are not endless. If delivery never succeeds — the app does not answer `2xx`, the server never comes up, or it has been deleted — the platform messages the server owner in Bitrix24 chat and stops delivering calls for that handler. The receiver still accepts subsequent calls from Bitrix24, but they no longer reach the app, and there is no second message. Delivery resumes once you register the handler again or update it with the `handler` field.

## Changing the handler

Changing `handler` to a Black Hole subdomain switches the activity or automation rule to reliable delivery. Changing it back to an address on your own domain restores direct calls without retries.

A request without the `handler` field leaves the binding as it is: updating any other field keeps the delivery exactly as it was set at registration.

## Registration requires a single request

A handler on a Black Hole subdomain can only be registered or changed with a single call — the platform needs a separate request to set up the delivery. A [batch call](/docs/batch) rejects such a registration, and the form of the rejection depends on where the batch was sent.

| Where the batch was sent | What arrives |
|---|---|
| `POST /v1/batch` | `BIZPROC_CALLBACK_BATCH_UNSUPPORTED` in `data.errors` under that call's `id`. The other calls in the batch still run, and if there are no other calls in the batch, the whole request returns `400` |
| `POST /v1/{entity}/batch` | `400 BATCH_ITEM_VALIDATION` for the whole batch. The name `BIZPROC_CALLBACK_BATCH_UNSUPPORTED` and the item index arrive inside `message` |

A handler on your own domain can be registered or changed through a batch call in both cases.

## Enabled per Bitrix24 account

Reliable delivery is enabled per Bitrix24 account. Until it is enabled for your account, registration works as before: the handler address stays yours and calls come directly from Bitrix24. The `SERVER_APP_MISMATCH` rejection and the batch-registration restriction apply only when reliable delivery is enabled.

## Public mode and auto-sleep

[Public mode](/docs/infra/access/access-policy) is never needed for activity and automation rule calls: such a call passes the access check by its own marker, regardless of the server's access policy.

Auto-sleep does not have to be turned off either, but only once reliable delivery is enabled: the call arrives at the platform receiver, and the platform wakes the sleeping server itself and brings the call through the tunnel. Until delivery is enabled for the account, Bitrix24 calls the subdomain directly, and a call that arrives at a sleeping server is lost — a direct call has no retries. Keep the server online until then, the same as for [Bitrix24 events](/docs/infra/app-runtime).

The rejection codes of each operation are listed on its own page. The full list of common API errors — [Errors](/docs/errors).

## See also

- [Business process activities](/docs/entities/bizproc-activities)
- [Automation rules](/docs/entities/bizproc-robots)
- [What the app receives](/docs/infra/app-runtime)
- [Portal event subscriptions](/docs/infra/event-subscriptions)
- [Batch](/docs/batch)